Regions API Basics

Liferay 7.4 U24+ and GA24+

Use Liferay’s REST APIs to create and manage regions.

Adding a Region

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

   curl https://resources.learn.liferay.com/dxp/latest/en/users-and-permissions/developer-guide/liferay-r2p3.zip -O
   

   unzip liferay-r2p3.zip
   

2. Use the cURL script to add a new region to a country. On the command line, navigate to the curl folder. Execute the Region_POST_ToCountry.sh script.

   ./Region_POST_ToCountry.sh 1234
   

   Replace 1234 with a country’s ID. Use Get Countries from Instance to get a list of IDs.

   The JSON response shows a new Region has been added:

   {
     "active" : true,
     "countryId" : 43501,
     "id" : 43503,
     "name" : "Foo",
     "position" : 0.0,
     "regionCode" : "ABL",
     "title_i18n" : { }
   }
   

3. The REST service can also be called using the Java client. Navigate out of the curl folder and into the java folder. Compile the source files:

   javac -classpath .:* *.java
   

4. Run the Region_POST_ToCountry.java class:

   java -classpath .:* -DcountryId=1234 Region_POST_ToCountry
   

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-admin-address/v1.0/countries/${1}/regions" \
	--data-raw '
		{
			"name": "Foo",
			"regionCode": "ABL"
		}' \
	--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-admin-address/v1.0/countries/${1}/regions"	The REST service endpoint
-d "{\"name\": \"Foo\", \"regionCode\": \"ABL\"}"	The data you are requesting 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 uses OAuth2.

The other cURL commands use similar JSON arguments.

Examine the Java Class

The Region_POST_ToCountry.java class adds a region by calling the Region-related service.

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

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

	Region region = regionResource.postCountryRegion(
		Long.valueOf(System.getProperty("countryId")),
		new Region() {
			{
				name = "Foo";
				regionCode = "ABL";
			}
		});

	System.out.println(region);
}

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

Line (abbreviated)	Description
RegionResource.Builder builder = ...	Gets a Builder for generating an RegionResource service instance.
RegionResource regionResource = builder.authentication(...).build();	Specifies basic authentication and generates a RegionResource service instance.
Region region = regionResource.postRegion(...);	Calls the regionResource.postRegion method and passes the data to post.

Note that the project includes the com.liferay.headless.admin.address.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 RegionResource methods.

important

See RegionResource for service details.

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

Get Regions from Instance

You can list regions by executing the following cURL or Java command.

Regions_GET_FromInstance.sh

Command:

./Regions_GET_FromInstance.sh

Code:

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

Regions_GET_FromInstance.java

Command:

java -classpath .:* Regions_GET_FromInstance

Code:

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

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

	Page<Region> page = regionResource.getRegionsPage(
		null, null, Pagination.of(1, 2), null);

	System.out.println(page);
}

The Instance’s Region objects appear in JSON.

Get a Region

Get a specific region with the following cURL or Java command.

tip

Use Regions_GET_FromInstance.[java|sh] to get instance Region IDs.

Region_GET_ById.sh

Command:

./Region_GET_ById.sh 1234

Code:

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

Region_GET_ById.java

Command:

java -classpath .:* -DregionId=1234 Region_GET_ById

Code:

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

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

	System.out.println(
		regionResource.getRegion(
			Long.valueOf(System.getProperty("regionId"))));
}

The Region fields appear in JSON.

Patch a Region

Do a partial edit of an existing Region with the following cURL and Java commands. Replace 1234 with your Region’s ID.

Region_PATCH_ById.sh

Command:

./Region_PATCH_ById.sh 1234

Code:

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

Region_PATCH_ById.java

Command:

java -classpath .:* -DregionId=1234 Region_PATCH_ById

Code:

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

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

	Region region = regionResource.patchRegion(
		Long.valueOf(System.getProperty("regionId")),
		new Region() {
			{
				name = "Bar";
			}
		});

	System.out.println(region);
}

Put a Region

Completely overwrite an existing region with the following cURL and Java commands. Replace 1234 with your region’s ID.

Region_PUT_ById.sh

Command:

./Region_PUT_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-address/v1.0/regions/${1}" \
	--data-raw '
		{
			"name": "Goo",
			"regionCode": "ABL"
		}' \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "[e-mail]:learn"

Region_PUT_ById.java

Command:

java -classpath .:* -DregionId=1234 Region_PUT_ById

Code:

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

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

	Region region = regionResource.putRegion(
		Long.valueOf(System.getProperty("regionId")),
		new Region() {
			{
				name = "Goo";
				regionCode = "ABL";
			}
		});

	System.out.println(region);
}

Delete a Region

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

Region_DELETE_ById.sh

Command:

./Region_DELETE_ById.sh 1234

Code:

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

Region_DELETE_ById.java

Command

java -classpath .:* -DregionId=1234 Region_DELETE_ById

Code:

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

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

	regionResource.deleteRegion(
		Long.valueOf(System.getProperty("regionId")));
}

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