Specification API Basics

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

Adding a Specification

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 [e-mail] and the password test. When prompted, change the password to learn.

Once Liferay is running,

1. Download and unzip Specification API Basics.

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

   unzip liferay-u9x9.zip
   

2. Specifications are scoped to an instance, and each specification must specify a unique key and a title.

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

   ./Specification_POST_ToInstance.sh
   

   The JSON response shows a new specification was added:

   {
      "description" : { },
      "facetable" : false,
      "id" : 45936,
      "key" : "foo",
      "title" : {
         "en_US" : "Foo"
      }
   }
   

3. To verify the specification addition, open the Global Menu () and navigate to Commerce → Specifications. The new specification appears under the Specification Labels tab.

   

   note

   Currently, the API cannot add a specification label to a specification group or create a specification group. You must instead use the Specifications UI. Open the Global Menu () and navigate to Commerce → Specifications. See Specification Groups for more information.

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 Specification_POST_ToInstance class.

   java -classpath .:* Specification_POST_ToInstance
   

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/specifications" \
	--data-raw '
		{
			"key": "foo",
			"title": {
				"en_US": "Foo"
			}
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "[e-mail]: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/specifications"	Specify the REST service endpoint.
-d "{\"key\": \"foo\", \"title\": {\"en_US\": \"Foo\"}}"	Enter the data to post.
-u "[e-mail]: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 Specification_POST_ToInstance.java class adds a specification by calling the SpecificationResource service.

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

	SpecificationResource specificationResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		specificationResource.postSpecification(
			new Specification() {
				{
					key = "foo";
					title = new HashMap<String, String>() {
						{
							put("en_US", "Foo");
						}
					};
				}
			}));
}

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

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

important

See SpecificationResource for service details.

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

Get Specifications from Instance

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

Specifications_GET_FromInstance.sh

Command:

./Specifications_GET_FromInstance.sh

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/specifications" \
	--user "[e-mail]:learn"

Specifications_GET_FromInstance.java

Command:

java -classpath .:* Specifications_GET_FromInstance

Code:

	SpecificationResource specificationResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		specificationResource.getSpecificationsPage(
			null, null, Pagination.of(1, 2), null));
}

}

The instance’s Specification objects are formatted in JSON.

Filtering, Paginating, Searching, and Sorting Specifications

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

• key
• title

Filter Query	Description
key eq 'foo'	The specification key must equal foo.
title eq 'Bar'	The specification title must be Bar.

Sort Query	Description
key:desc	Sort by key in descending order.
title:asc	Sort by title in ascending order.

Read API Query Parameters for more information.

Get a Specification

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

tip

Use Specifications_GET_FromInstance.[java|sh] to get a list of all specifications, and note the id of the specification you want specifically.

Specification_GET_ById.sh

Command:

./Specification_GET_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/specifications/${1}" \
	--user "[e-mail]:learn"

Specification_GET_ById.java

Command:

java -classpath .:* -DspecificationId=1234 Specification_GET_ById

Code:

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

	SpecificationResource specificationResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	System.out.println(
		specificationResource.getSpecification(
			Long.valueOf(System.getProperty("specificationId"))));
}

The Specification fields are listed in JSON.

Patch a Specification

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

Specification_PATCH_ById.sh

Command:

./Specification_PATCH_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/specifications/${1}" \
	--data-raw '
		{
			"key": "bar",
			"title": {
				"en_US": "Bar"
			}
		}' \
	--header "Content-Type: application/json" \
	--request "PATCH" \
	--user "[e-mail]:learn"

Specification_PATCH_ById.java

Command:

java -classpath .:* -DspecificationId=1234 Specification_PATCH_ById

Code:

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

	SpecificationResource specificationResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	specificationResource.patchSpecification(
		Long.valueOf(System.getProperty("specificationId")),
		new Specification() {
			{
				key = "bar";
				title = new HashMap<String, String>() {
					{
						put("en_US", "Bar");
					}
				};
			}
		});
}

Delete a Specification

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

Specification_DELETE_ById.sh

Command:

./Specification_DELETE_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/specifications/${1}" \
	--request "DELETE" \
	--user "[e-mail]:learn"

Specification_DELETE_ById.java

Command

java -classpath .:* -DspecificationId=1234 Specification_DELETE_ById

Code:

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

	SpecificationResource specificationResource = builder.authentication(
		"[e-mail]", "learn"
	).build();

	specificationResource.deleteSpecification(
		Long.valueOf(System.getProperty("specificationId")));
}

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