Submit Feedback

Catalog API Basics

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

Adding a Catalog

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 Catalog API Basics.

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

unzip liferay-q2v8.zip

Catalogs are scoped to an instance. Use the cURL script to add a new catalog. On the command line, navigate to the curl folder. Execute the Catalog_POST_ToInstance.sh script.

./Catalog_POST_ToInstance.sh

The JSON response shows a new catalog was added:

{
   "actions" : {
      "get" : {
         "method" : "GET",
         "href" : "http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/catalog/46110"
      },
      "update" : {
         "method" : "PATCH",
         "href" : "http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/catalog/46110"
      },
      "delete" : {
         "method" : "DELETE",
         "href" : "http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/catalog/46110"
      }
   },
   "currencyCode" : "USD",
   "defaultLanguageId" : "en_US",
   "externalReferenceCode" : "246ad89e-8da1-546c-0d62-06ac7061e1da",
   "id" : 46110,
   "name" : "Able",
   "system" : false
}

To verify the catalog addition, open the Global Menu () and navigate to Commerce → Catalogs. The new catalog appears.
Alternatively, call the REST service using the Java client. Navigate into the java folder and compile the source files:
```
javac -classpath .:* *.java
```

Run the Catalog_POST_ToInstance class.

java -classpath .:* Catalog_POST_ToInstance

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-commerce-admin-catalog/v1.0/catalogs" \
	--data-raw '
		{
			"currencyCode": "USD",
			"defaultLanguageId": "en_US",
			"name": "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/catalogs"`	Specify the REST service endpoint.
`-d "{\"currencyCode\": \"USD\", \"defaultLanguageId\": \"en_US\", \"name\": \"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 Catalog_POST_ToInstance.java class adds a catalog by calling the CatalogResource service.

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

	CatalogResource catalogResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		catalogResource.postCatalog(
			new Catalog() {
				{
					currencyCode = "USD";
					defaultLanguageId = "en_US";
					name = "Able";
				}
			}));
}

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

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

important

See CatalogResource for service details.

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

Get Catalogs from Instance

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

Catalogs_GET_FromInstance.sh

Command:

./Catalogs_GET_FromInstance.sh

Code:

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

Catalogs_GET_FromInstance.java

Command:

java -classpath .:* Catalogs_GET_FromInstance

Code:

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

	CatalogResource catalogResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	Page<Catalog> page = catalogResource.getCatalogsPage(
		null, null, Pagination.of(1, 2), null);

	System.out.println(page);
}

The instance’s Catalog objects are formatted in JSON.

Filtering, Paginating, Searching, and Sorting Catalogs

This API also accepts parameters to filter, paginate, search, and sort the catalogs. See the getCatalogsPage method for more information. You can use the name field to filter, search, and sort the results.

Filter Query	Description
`name eq 'Able'`	The catalog name must equal Able.

Sort Query	Description
`name:desc`	Sort by name in descending order.

Read API Query Parameters for more information.

Get a Catalog

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

tip

Use Catalogs_GET_FromInstance.[java|sh] to get a list of all catalogs, and note the id of the catalog you want specifically.

Catalog_GET_ById.sh

Command:

./Catalog_GET_ById.sh 1234

Code:

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

Catalog_GET_ById.java

Command:

java -classpath .:* -DcatalogId=1234 Catalog_GET_ById

Code:

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

	CatalogResource catalogResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		catalogResource.getCatalog(
			Long.valueOf(System.getProperty("catalogId"))));
}

The Catalog fields are listed in JSON.

Patch a Catalog

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

Catalog_PATCH_ById.sh

Command:

./Catalog_PATCH_ById.sh 1234

Code:

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

Catalog_PATCH_ById.java

Command:

java -classpath .:* -DcatalogId=1234 Catalog_PATCH_ById

Code:

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

	CatalogResource catalogResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	catalogResource.patchCatalog(
		Long.valueOf(System.getProperty("catalogId")),
		new Catalog() {
			{
				name = "Bar";
			}
		});
}

Delete a Catalog

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

Catalog_DELETE_ById.sh

Command:

./Catalog_DELETE_ById.sh 1234

Code:

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

Catalog_DELETE_ById.java

Command

java -classpath .:* -DcatalogId=1234 Catalog_DELETE_ById

Code:

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

	CatalogResource catalogResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	catalogResource.deleteCatalog(
		Long.valueOf(System.getProperty("catalogId")));
}

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

Capability: