Product API Basics

You can manage products from the Applications menu, but you can also use Liferay’s REST APIs. Call these services to create and manage products.

Adding a Product

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.

Then follow these steps:

1. Download and unzip Product API Basics.

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

   unzip liferay-z8v2.zip
   

2. A product is scoped to a catalog and the catalog ID is one of the required parameters. To get this, open the Global Menu (), and go to Commerce → Catalogs. Select the catalog where you’ll add products and note down the ID present next to its name.

   

3. Use the cURL script to add a new product to the catalog. On the command line, navigate to the curl folder. Execute the Product_POST_ToCatalog.sh script with your catalog ID as a parameter.

   ./Product_POST_ToCatalog.sh 1234
   

   The JSON response shows a new product has been added:

   "actions" : {
    "get" : {
      "method" : "GET",
      "href" : "http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/products/47738"
    },
    "update" : {
      "method" : "PATCH",
      "href" : "http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/products/47738"
    },
    "delete" : {
      "method" : "DELETE",
      "href" : "http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/products/47738"
    }
   },
   "active" : true,
   "catalogId" : 47734,
   "categories" : [ ],
   "createDate" : "2022-10-14T09:58:20Z",
   "customFields" : [ ],
   "description" : {
      "en_US" : ""
   },
   "displayDate" : "2022-10-14T09:58:00Z",
   "expando" : { },
   "externalReferenceCode" : "5ad0eabb-6c69-6eaf-75aa-ec4000408c66",
   "id" : 47738,
   "metaDescription" : {
      "en_US" : ""
   },
   "metaKeyword" : {
      "en_US" : ""
   },
   "metaTitle" : {
      "en_US" : ""
   },
   "modifiedDate" : "2022-10-14T09:58:20Z",
   "name" : {
      "en_US" : "Foo"
   },
   "productAccountGroupFilter" : false,
   "productChannelFilter" : false,
   "productId" : 47739,
   "productStatus" : 0,
   "productType" : "simple",
   "productTypeI18n" : "Simple",
   "shortDescription" : {
      "en_US" : ""
   },
   "skuFormatted" : "",
   "tags" : [ ],
   "thumbnail" : "/o/commerce-media/default/?groupId=47735",
   "urls" : {
      "en_US" : "foo"
   },
   "version" : 1,
   "workflowStatusInfo" : {
      "code" : 0,
      "label" : "approved",
      "label_i18n" : "Approved"
   }
   

4. Verify this by opening the Global Menu (), and navigating to Commerce → Products. See that a new product has been added.

   

5. You can also call the The REST service using the Java client. Navigate out of the curl folder and into the java folder. Compile the source files:

   javac -classpath .:* *.java
   

6. Run the Product_POST_ToCatalog class. Replace the catalogId value with your Catalog’s ID:

   java -classpath .:* -DcatalogId=1234 Product_POST_ToCatalog
   

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/products" \
	--data-raw '
		{
			"active": true,
			"catalogId": "'"${1}"'",
			"name": {
				"en_US": "Foo"
			},
			"productType": "simple"
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "[e-mail]:learn"

Here are the command’s arguments:

Arguments	Description
-H "Content-Type: application/json"	Indicates that the request body format is JSON.
-X POST	The HTTP method to invoke at the specified endpoint
"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/products"	The REST service endpoint
-d "{\"active\": true, \"catalogId\": \"${1}\", \"name\": {\"en_US\": \"Foo\"}, \"productType\": \"simple\"}"	The data to post
-u "[e-mail]:learn"	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 that utilizes OAuth2.

The other cURL commands use similar JSON arguments.

Examine the Java Class

The Product_POST_ToCatalog.java class adds a product by calling the product related service.

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

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

	System.out.println(
		productResource.postProduct(
			new Product() {
				{
					active = true;
					catalogId = Long.valueOf(
						System.getProperty("catalogId"));
					name = new HashMap<String, String>() {
						{
							put("en_US", "Foo");
						}
					};
					productType = "simple";
				}
			}));
}

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

Line (abbreviated)	Description
ProductResource.Builder builder = ...	Gets a Builder for generating a ProductResource service instance.
ProductResource productResource = builder.authentication(...).build();	Specifies basic authentication and generates a ProductResource service instance.
productResource.postProduct(...);	Calls the productResource.postProduct method and passes the data to post.

Note that 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.

Note

The main method’s comment demonstrates running the class.

The other example Java classes are similar to this one, but call different ProductResource methods.

Important

See ProductResource for service details.

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

Get Products from Instance

You can list all products from your Liferay instance by executing the following cURL or Java command.

Products_GET_FromInstance.sh

Command:

./Products_GET_FromInstance.sh

Code:

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

Products_GET_FromInstance.java

Command:

java -classpath .:* Products_GET_FromInstance

Code:

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

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

	Page<Product> page = productResource.getProductsPage(
		null, null, Pagination.of(1, 2), null);

	System.out.println(page);
}

The Product objects of your Liferay instance are listed in JSON.

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

• categoryIds
• channelId
• statusCode
• customFields
• createDate
• modifiedDate
• catalogId
• name
• productType

Filter Query	Description
productType eq ‘simple’	Product type equals simple
contains(name, ‘Bar’)	Product name contains Bar
customFields/sampleSize eq ‘100.0’	Custom field named sampleSize equals 100

Sort Query	Description
createDate:desc	Sort by createDate in the descending order
name:asc	Sort by name in the ascending order
createDate:desc,name:desc	Sort by createDate in the descending order first, then by name in the descending order

Read API Query Parameters for more information.

Get a Product

Get a specific product with the following cURL or Java command. Replace 1234 with the product’s ID.

Tip

Use Products_GET_FromInstance.[java|sh] to get a list of all products, and note the productId of the product you want specifically.

Product_GET_ById.sh

Command:

./Product_GET_ById.sh 1234

Code:

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

Product_GET_ById.java

Command:

java -classpath .:* -DproductId=1234 Product_GET_ById

Code:

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

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

	System.out.println(
		productResource.getProduct(
			Long.valueOf(System.getProperty("productId"))));
}

The Product fields are listed in JSON.

Patch a Product

Update an existing product with the following cURL and Java commands. Replace 1234 with your product’s ID.

Product_PATCH_ById.sh

Command:

./Product_PATCH_ById.sh 1234

Code:

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

Product_PATCH_ById.java

Command:

java -classpath .:* -DproductId=1234 Product_PATCH_ById

Code:

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

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

	productResource.patchProduct(
		Long.valueOf(System.getProperty("productId")),
		new Product() {
			{
				name = new HashMap<String, String>() {
					{
						put("en_US", "Bar");
					}
				};
			}
		});
}

Delete a Product

Delete an existing product with the following cURL and Java commands. Replace 1234 with your product’s ID.

Product_DELETE_ById.sh

Command:

./Product_DELETE_ById.sh 1234

Code:

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

Product_DELETE_ById.java

Command

java -classpath .:* -DproductId=1234 Product_DELETE_ById

Code:

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

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

	productResource.deleteProduct(
		Long.valueOf(System.getProperty("productId")));
}

The API Explorer lists all of the Product services and schemas and has an interface to try out each service.

Related Topics

-Consuming REST Services