Option API Basics

You can manage option templates from the Applications menu or with REST APIs. Call the headless-commerce-admin-catalog services to create and manage options.

Adding an Option

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:2024.q1.1

Sign in to Liferay at http://localhost:8080 using the email address test@liferay.com and the password test. When prompted, change the password to learn.

Once Liferay is running,

  1. Download and unzip Option API Basics.

    curl https://resources.learn.liferay.com/commerce/latest/en/product-management/developer-guide/liferay-d3g5.zip -O
    
    unzip liferay-d3g5.zip
    
  2. Options are scoped to an instance, and each option must specify a unique key.

    Use the cURL script to add a new option. On the command line, navigate to the curl folder. Execute the Option_POST_ToInstance.sh script.

    ./Option_POST_ToInstance.sh
    

    The JSON response shows a new option was added:

    {
       "actions" : {
          "get" : {
             "method" : "GET",
             "href" : "http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/options/46438"
          },
          "update" : {
             "method" : "PATCH",
             "href" : "http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/options/46438"
          },
          "delete" : {
             "method" : "DELETE",
             "href" : "http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/options/46438"
          }
       },
       "description" : { },
       "externalReferenceCode" : "f73e12cd-feae-9e78-5921-6b65f6b993f6",
       "facetable" : false,
       "fieldType" : "select",
       "id" : 46438,
       "key" : "foo",
       "name" : {
          "en_US" : "Foo"
       },
       "required" : false,
       "skuContributor" : false
    }
    
  3. To verify the option addition, open the Global Menu (Applications Menu icon) and navigate to CommerceOptions. The new option appears.

    Confirm that a new option was added.

  4. Alternatively, call the REST service using the Java client. Navigate into the java folder and compile the source files:

    javac -classpath .:* *.java
    
  5. Run the Option_POST_ToInstance class.

    java -classpath .:* Option_POST_ToInstance
    

The following option field types are available when creating an option.

Field TypeAPI Value
Text"fieldType": "text"
Select From List"fieldType": "select"
Single Selection"fieldType": "radio"
Multiple Selection"fieldType": "checkbox_multiple"
Date"fieldType": "date"
Numeric"fieldType": "numeric"
Boolean"fieldType": "checkbox"

Examine the cURL Command

The Option_POST_ToInstance.sh script calls the REST service with a cURL command.

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/options" \
	--data-raw '
		{
			"fieldType": "select",
			"key": "foo",
			"name": {
				"en_US": "Foo"
			}
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"

Here are the command’s arguments:

ArgumentsDescription
-H "Content-Type: application/json"Set the request body format to JSON.
-X POSTSet the HTTP method to invoke at the specified endpoint.
"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/options"Specify the REST service endpoint.
-d "{\"fieldType\": \"select\", \"key\": \"foo\", \"name\": {\"en_US\": \"Foo\"}}"Enter the data to post.
-u "test@liferay.com:learn"Enter basic authentication credentials.
Note

Basic authentication is used here for demonstration purposes. For production, you should authorize users via OAuth2. See Using OAuth2 to Authorize Users for a sample React application using OAuth2.

The other cURL commands use similar JSON arguments.

Examine the Java Class

The Option_POST_ToInstance.java class adds an option by calling the OptionResource service.

public static void main(String[] args) throws Exception {
	OptionResource.Builder builder = OptionResource.builder();

	OptionResource optionResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		optionResource.postOption(
			new Option() {
				{
					fieldType = Option.FieldType.SELECT;
					key = "foo";
					name = new HashMap<String, String>() {
						{
							put("en_US", "Foo");
						}
					};
				}
			}));
}

This class invokes the REST service using only three lines of code:

Line (abbreviated)Description
OptionResource.Builder builder = ...Get a Builder for generating a OptionResource service instance.
OptionResource optionResource = builder.authentication(...).build();Use basic authentication and generate a OptionResource service instance.
optionResource.postOption(...);Call the optionResource.postOption method and pass the data to post.

The project includes the com.liferay.headless.commerce.admin.catalog.client.jar file as a dependency. You can find client JAR dependency information for all REST applications in the API Explorer in your installation at /o/api (e.g., http://localhost:8080/o/api).

Note

The main method’s comment demonstrates running the class.

The remaining example Java classes call different OptionResource methods.

Important

See OptionResource for service details.

Below are examples of calling other Option REST services using cURL and Java.

Get Options from Instance

List all the options in your Liferay instance with a cURL or Java command.

Options_GET_FromInstance.sh

Command:

./Options_GET_FromInstance.sh

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/options" \
	--user "test@liferay.com:learn"

Options_GET_FromInstance.java

Command:

java -classpath .:* Options_GET_FromInstance

Code:

 */
public static void main(String[] args) throws Exception {
	OptionResource.Builder builder = OptionResource.builder();

	OptionResource optionResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		optionResource.getOptionsPage(
			null, null, Pagination.of(1, 2), null));

The instance’s Option objects are formatted in JSON.

Filtering, Paginating, Searching, and Sorting Options

This API also accepts parameters to filter, paginate, search, and sort the options. See the getOptionsPage method for more information. You can use the following Option fields in your queries to filter, search, and sort the results:

  • fieldType
  • key
  • name
Filter QueryDescription
name eq 'Able'The option name must equal Able.
fieldType eq 'select'The option type must be select.
Sort QueryDescription
key:descSort by key in descending order.
name:descSort by name in descending order.

Read API Query Parameters for more information.

Get an Option

Get a specific option with cURL or Java get commands. Replace 1234 with the option’s ID.

tip

Use Options_GET_FromInstance.[java|sh] to get a list of all options, and note the id of the option you want specifically.

Option_GET_ById.sh

Command:

./Option_GET_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/options/${1}" \
	--user "test@liferay.com:learn"

Option_GET_ById.java

Command:

java -classpath .:* -DoptionId=1234 Option_GET_ById

Code:

public static void main(String[] args) throws Exception {
	OptionResource.Builder builder = OptionResource.builder();

	OptionResource optionResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		optionResource.getOption(
			Long.valueOf(System.getProperty("optionId"))));
}

The Option fields are listed in JSON.

Patch an Option

Update an existing option with cURL and Java patch commands. Replace 1234 with your option’s ID.

Option_PATCH_ById.sh

Command:

./Option_PATCH_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/options/${1}" \
	--data-raw '
		{
			"fieldType": "radio",
			"key": "bar",
			"name": {
				"en_US": "Bar"
			}
		}' \
	--header "Content-Type: application/json" \
	--request "PATCH" \
	--user "test@liferay.com:learn"

Option_PATCH_ById.java

Command:

java -classpath .:* -DoptionId=1234 Option_PATCH_ById

Code:

public static void main(String[] args) throws Exception {
	OptionResource.Builder builder = OptionResource.builder();

	OptionResource optionResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	optionResource.patchOption(
		Long.valueOf(System.getProperty("optionId")),
		new Option() {
			{
				fieldType = Option.FieldType.RADIO;
				key = "bar";
				name = new HashMap<String, String>() {
					{
						put("en_US", "Bar");
					}
				};
			}
		});
}

Delete an Option

Delete an existing option with cURL and Java delete commands. Replace 1234 with your option’s ID.

Option_DELETE_ById.sh

Command:

./Option_DELETE_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/options/${1}" \
	--request "DELETE" \
	--user "test@liferay.com:learn"

Option_DELETE_ById.java

Command

java -classpath .:* -DoptionId=1234 Option_DELETE_ById

Code:

public static void main(String[] args) throws Exception {
	OptionResource.Builder builder = OptionResource.builder();

	OptionResource optionResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	optionResource.deleteOption(
		Long.valueOf(System.getProperty("optionId")));
}

The API Explorer shows the Option services and schemas and has an interface to test each service.

Capabilities

Product

Contact Us

Connect

Powered by Liferay
© 2024 Liferay Inc. All Rights Reserved • Privacy Policy