Channel API Basics

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

Adding a Channel

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

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

   unzip liferay-a2t5.zip
   

2. Channels are scoped to an instance, and each channel must specify a currencyCode, name, and type. One type, site, is available out-of-the-box.

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

   ./Channel_POST_ToInstance.sh
   

   The JSON response shows a new channel was added:

   {
      "currencyCode" : "USD",
      "externalReferenceCode" : "29f395e8-779c-e95e-36f6-844a1ebf00c4",
      "id" : 46901,
      "name" : "Foo",
      "siteGroupId" : 0,
      "type" : "site"
   }
   

3. To verify the channel addition, open the Global Menu () and navigate to Commerce → Channels. The new channel appears.

   

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

   java -classpath .:* Channel_POST_ToInstance
   

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-commerce-admin-channel/v1.0/channels" \
	--data-raw '
		{
			"currencyCode": "USD",
			"name": "Foo",
			"type": "site"
		}' \
	--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-channel/v1.0/channels"	Specify the REST service endpoint.
-d "{\"currencyCode\": \"USD\", \"name\": \"Foo\", \"type\": \"site\"}"	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 Channel_POST_ToInstance.java class adds a channel by calling the ChannelResource service.

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

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

	System.out.println(
		channelResource.postChannel(
			new Channel() {
				{
					currencyCode = "USD";
					name = "Foo";
					type = "site";
				}
			}));
}

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

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

The project includes the com.liferay.headless.commerce.admin.channel.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 ChannelResource methods.

important

See ChannelResource for service details.

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

Get Channels from Instance

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

Channels_GET_FromInstance.sh

Command:

./Channels_GET_FromInstance.sh

Code:

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

Channels_GET_FromInstance.java

Command:

java -classpath .:* Channels_GET_FromInstance

Code:

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

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

	System.out.println(
		channelResource.getChannelsPage(
			null, null, Pagination.of(1, 2), null));
}

The instance’s Channel objects are formatted in JSON.

Filtering, Paginating, Searching, and Sorting Channels

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

• name
• siteGroupId

Filter Query	Description
siteGroupId eq '12345'	The channel siteGroupId must equal 12345.
name eq 'Foo'	The channel name must equal Foo.

Sort Query	Description
name:desc	Sort by name in descending order.
siteGroupId:asc	Sort by siteGroupId in ascending order.

Read API Query Parameters for more information.

Get a Channel

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

tip

Use Channels_GET_FromInstance.[java|sh] to get a list of all channels, and note the id of the channel you want specifically.

Channel_GET_ById.sh

Command:

./Channel_GET_ById.sh 1234

Code:

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

Channel_GET_ById.java

Command:

java -classpath .:* -DchannelId=1234 Channel_GET_ById

Code:

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

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

	System.out.println(
		channelResource.getChannel(
			Long.valueOf(System.getProperty("channelId"))));
}

The Channel fields are listed in JSON.

Patch a Channel

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

Channel_PATCH_ById.sh

Command:

./Channel_PATCH_ById.sh 1234

Code:

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

Channel_PATCH_ById.java

Command:

java -classpath .:* -DchannelId=1234 Channel_PATCH_ById

Code:

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

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

	channelResource.patchChannel(
		Long.valueOf(System.getProperty("channelId")),
		new Channel() {
			{
				name = "Bar";
			}
		});
}

Delete a Channel

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

Channel_DELETE_ById.sh

Command:

./Channel_DELETE_ById.sh 1234

Code:

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

Channel_DELETE_ById.java

Command

java -classpath .:* -DchannelId=1234 Channel_DELETE_ById

Code:

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

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

	channelResource.deleteChannel(
		Long.valueOf(System.getProperty("channelId")));
}

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