Option Value API Basics

You can manage option values from the Options application or with REST APIs. Call the headless-commerce-admin-catalog services to create and manage option values.

Adding an Option Value

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,

Download and unzip Option Value API Basics.

curl https://resources.learn.liferay.com/commerce/latest/en/product-management/developer-guide/liferay-c7w9.zip -O

unzip liferay-c7w9.zip

Option values are scoped to an option. If you haven’t created an option, see Option API Basics. When creating a new option value, you must provide the id of the option, a unique key, and a name for the option value.

Use the cURL script to add a new option value. On the command line, navigate to the curl folder. Execute the OptionValue_POST_ToOption.sh script with the appropriate option ID as a parameter.

./OptionValue_POST_ToOption.sh 1234

The JSON response shows a new option value was added:

{
   "actions" : {
      "get" : {
         "method" : "GET",
         "href" : "http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/optionValues/{id}"
      },
      "update" : {
         "method" : "PATCH",
         "href" : "http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/optionValues/{id}"
      },
      "delete" : {
         "method" : "DELETE",
         "href" : "http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/optionValues/{id}"
      }
   },
   "externalReferenceCode" : "c63216c7-9043-90ab-35b9-6efbe36b47ff",
   "id" : 46709,
   "key" : "able",
   "name" : {
      "en_US" : "Able"
   },
   "priority" : 0.0
}

To verify the option value addition, open the Global Menu () and navigate to Commerce → Options. Select the appropriate option. The new option value appears in the Values section.
Alternatively, call the REST service using the Java client. Navigate into the java folder and compile the source files:
```
javac -classpath .:* *.java
```
Run the OptionValue_POST_ToOption class, replacing the optionId with the appropriate value.
```
java -classpath .:* -DoptionId=1234 OptionValue_POST_ToOption
```

Examine the cURL Command

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

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

Here are the command’s arguments:

Arguments	Description
`-H "Content-Type: application/json"`	Set the request body format to JSON.
`-X POST`	Set the HTTP method to invoke at the specified endpoint.
`"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/options/${1}/optionValues"`	Specify the REST service endpoint.
`-d "{\"key\": \"able\", \"name\": {\"en_US\": \"Able\"}}"`	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 OptionValue_POST_ToOption.java class adds an option value by calling the OptionValueResource service.

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

	OptionValueResource optionValueResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		optionValueResource.postOptionIdOptionValue(
			Long.valueOf(System.getProperty("optionId")),
			new OptionValue() {
				{
					key = "able";
					name = new HashMap<String, String>() {
						{
							put("en_US", "Able");
						}
					};
				}
			}));
}

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

Line (abbreviated)	Description
`OptionValueResource.Builder builder = ...`	Get a `Builder` for generating a `OptionValueResource` service instance.
`OptionValueResource optionValueResource = builder.authentication(...).build();`	Use basic authentication and generate a `OptionValueResource` service instance.
`optionValueResource.postOption(...);`	Call the `optionValueResource.postOptionIdOptionValue` 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 OptionValueResource methods.

important

See OptionValueResource for service details.

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

Get Option Values from an Option

List all the option values from an option with a cURL or Java command. Replace 1234 with the option’s ID.

OptionValues_GET_FromOption.sh

Command:

./OptionValues_GET_FromOption.sh 1234

Code:

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

OptionValues_GET_FromOption.java

Command:

java -classpath .:* -DoptionId=1234 OptionValues_GET_FromOption

Code:

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

	OptionValueResource optionValueResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		optionValueResource.getOptionIdOptionValuesPage(
			Long.valueOf(System.getProperty("optionId")), null,
			Pagination.of(1, 2), null));
}

The option’s OptionValue objects are formatted in JSON.

Get an Option Value

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

tip

Use OptionValues_GET_FromOption.[java|sh] to get a list of all option values associated to an option, and note the id of the option value you want specifically.

OptionValue_GET_ById.sh

Command:

./OptionValue_GET_ById.sh 1234

Code:

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

OptionValue_GET_ById.java

Command:

java -classpath .:* -DoptionValueId=1234 OptionValue_GET_ById

Code:

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

	OptionValueResource optionValueResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		optionValueResource.getOptionValue(
			Long.valueOf(System.getProperty("optionValueId"))));
}

The OptionValue fields are listed in JSON.

Patch an Option Value

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

OptionValue_PATCH_ById.sh

Command:

./OptionValue_PATCH_ById.sh 1234

Code:

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

OptionValue_PATCH_ById.java

Command:

java -classpath .:* -DoptionValueId=1234 OptionValue_PATCH_ById

Code:

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

	OptionValueResource optionValueResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	optionValueResource.patchOptionValue(
		Long.valueOf(System.getProperty("optionValueId")),
		new OptionValue() {
			{
				name = new HashMap<String, String>() {
					{
						put("en_US", "Baker");
					}
				};
			}
		});
}

Delete an Option Value

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

OptionValue_DELETE_ById.sh

Command:

./OptionValue_DELETE_ById.sh 1234

Code:

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

OptionValue_DELETE_ById.java

Command

java -classpath .:* -DoptionValueId=1234 OptionValue_DELETE_ById

Code:

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

	OptionValueResource optionValueResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	optionValueResource.deleteOptionValue(
		Long.valueOf(System.getProperty("optionValueId")));
}

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

Capability:

Commerce

Deployment Approach:

Liferay PaaS

Liferay SaaS

Liferay Self-Hosted

Feature:

Catalogs

Product Information

Products

Cloud

Commerce

Content Management System

Development and Tooling

Digital Asset Management

DXP Self-Hosted Installation, Maintenance, and Administration

Integration

Personalization

Platform

Search

Security

Sites

Analytics Cloud

Commerce

DXP

Liferay Cloud

Reference