Postal Address API Basics

Liferay DXP/Portal 7.4+

Use Liferay’s REST APIs to manage postal addresses.

Add Postal Address to Account

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:2024.q2.11

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.

Then, follow these steps:

Download and unzip Postal Address API Basics.

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

unzip liferay-n8y7.zip

Use Accounts_GET_FromInstance to get a list of accounts. Note the ID of the account where you’ll add a postal address. You can also navigate to Global Menu → Control Panel → Accounts to see the list of accounts.

Use the cURL script to add a new postal address to your chosen account. On the command line, navigate to the curl folder. Execute the PostalAddress_POST_ToAccount.sh script. Replace 1234 with an account ID.

./PostalAddress_POST_ToAccount.sh 1234

The JSON response shows a new postal address has been added:

{
  "addressCountry" : "United States",
  "addressLocality" : "Diamond Bar",
  "addressRegion" : "California",
  "addressType" : "shipping",
  "id" : 35706,
  "name" : "Able Address",
  "postalCode" : "12345",
  "primary" : false,
  "streetAddressLine1" : "123 Foo St",
  "streetAddressLine2" : "",
  "streetAddressLine3" : ""
}

Navigate to Global Menu → Control Panel → Accounts. Select the account you chose in Step 2 and navigate to Addresses. See that a new postal address has been added to the account.
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
```
Run the PostalAddress_POST_ToAccount.java class. Replace 1234 with an account ID.
```
java -classpath .:* -DaccountId=1234 PostalAddress_POST_ToAccount
```

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/accounts/${1}/postal-addresses" \
	--data-raw '
		{
			"addressCountry": "United States",
			"addressLocality": "Diamond Bar",
			"addressRegion": "California",
			"addressType": "shipping",
			"name": "Able Address",
			"postalCode": "12345",
			"primary": false,
			"streetAddressLine1": "123 Foo St",
			"streetAddressLine2": "",
			"streetAddressLine3": ""
		}' \
	--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"`	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-user/v1.0/accounts/${1}/postal-addresses"`	The REST service endpoint
`-d "{\"addressCountry\": \"United States\", \"addressLocality\": \"Diamond Bar\", \"addressRegion\": \"California\", \"addressType\": \"shipping\", \"name\": \"Able Address\", \"postalCode\": \"12345\", \"primary\": false, \"streetAddressLine1\": \"123 Foo St\", \"streetAddressLine2\": \"\", \"streetAddressLine3\": \"\"}"`	The data you are requesting to post
`-u "test@liferay.com: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 PostalAddress_POST_ToAccount.java class adds a postal address by calling the postal-address-related service.

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

	PostalAddressResource postalAddressResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	PostalAddress postalAddress =
		postalAddressResource.postAccountPostalAddress(
			Long.valueOf(System.getProperty("accountId")),
			new PostalAddress() {
				{
					addressCountry = "United States";
					addressLocality = "Diamond Bar";
					addressRegion = "California";
					addressType = "billing";
					name = "Charlie Address";
					postalCode = "91765";
					primary = false;
					streetAddressLine1 = "123 Foo St";
					streetAddressLine2 = "";
					streetAddressLine3 = "";
				}
			});

	System.out.println(postalAddress);
}

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

Line (abbreviated)	Description
`PostalAddress.Builder builder = ...`	Gets a `Builder` for generating a `PostalAddressResource` service instance.
`PostalAddressResource postalAddressResource = builder.authentication(...).build();`	Specifies basic authentication and generates a `PostalAddressResource` service instance.
`PostalAddress postalAddress = postalAddressResource.postAccountPostalAddress(...);`	Calls the `postalAddressResource.postAccountPostalAddress` method and passes the data to post.

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

Important

See PostalAddressResource for service details.

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

Get Postal Addresses from Account

Get a list of postal addresses from an account with the following cURL or Java command. Replace 1234 with the account’s ID.

PostalAddresses_GET_FromAccount.sh

Command:

./PostalAddresses_GET_FromAccount.sh 1234

Code:

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

PostalAddresses_GET_FromAccount.java

Command:

java -classpath .:* -DaccountId=1234 PostalAddresses_GET_FromAccount

Code:

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

	PostalAddressResource postalAddressResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		postalAddressResource.getAccountPostalAddressesPage(
			Long.valueOf(System.getProperty("accountId"))));
}

The account’s postal addresses are returned in the JSON response.

Get Postal Addresses from Organization

Get a list of postal addresses from an organization with the following cURL or Java command. Replace 1234 with the organization’s ID.

PostalAddresses_GET_FromOrganization.sh

Command:

./PostalAddresses_GET_FromOrganization.sh 1234

Code:

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

PostalAddresses_GET_FromOrganization.java

Command:

java -classpath .:* -DorganizationId=1234 PostalAddresses_GET_FromOrganization

Code:

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

	PostalAddressResource postalAddressResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		postalAddressResource.getOrganizationPostalAddressesPage(
			String.valueOf(System.getProperty("organizationId"))));
}

The organization’s postal addresses are returned in the JSON response.

Get Postal Addresses from User

Get a list of postal addresses from a user with the following cURL or Java command. Replace 1234 with the user’s ID.

PostalAddresses_GET_FromUser.sh

Command:

./PostalAddresses_GET_FromUser.sh 1234

Code:

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

PostalAddresses_GET_FromUser.java

Command:

java -classpath .:* -DuserAccountId=1234 PostalAddresses_GET_FromUser

Code:

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

	PostalAddressResource postalAddressResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		postalAddressResource.getUserAccountPostalAddressesPage(
			Long.valueOf(System.getProperty("userAccountId"))));
}

The user’s postal addresses are returned in the JSON response.

Get a Postal Address

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

Tip

Use PostalAddress_GET_FromAccount.[java|sh] to get account postal address IDs.

Use PostalAddress_GET_FromOrganization.[java|sh] to get organization postal address IDs.

Use PostalAddress_GET_FromUser.[java|sh] to get user postal address IDs.

PostalAddress_GET_ById.sh

Command:

./PostalAddress_GET_ById.sh 1234

Code:

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

PostalAddress_GET_ById.java

Command:

java -classpath .:* -DpostalAddressId=1234 PostalAddress_GET_ById

Code:

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

	PostalAddressResource postalAddressResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		postalAddressResource.getPostalAddress(
			Long.valueOf(System.getProperty("postalAddressId"))));
}

The postal address is returned in the JSON response.

Patch a Postal Address

Partially edit an existing postal address with the following cURL or Java command. Replace 1234 with the postal address’s ID.

PostalAddress_PATCH_ById.sh

Command:

./PostalAddress_PATCH_ById.sh 1234

Code:

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

PostalAddress_PATCH_ById.java

Command:

java -classpath .:* -DpostalAddressId=1234 PostalAddress_PATCH_ById

Code:

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

	PostalAddressResource postalAddressResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	PostalAddress postalAddress = postalAddressResource.patchPostalAddress(
		Long.valueOf(System.getProperty("postalAddressId")),
		new PostalAddress() {
			{
				streetAddressLine1 = "456 Bar Ave";
			}
		});

	System.out.println(postalAddress);
}

Put a Postal Address

Completely overwrite an existing postal address with the following cURL or Java command. Replace 1234 with the postal address’s ID.

PostalAddress_PUT_ById.sh

Command:

./PostalAddress_PUT_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-admin-user/v1.0/postal-addresses/${1}" \
	--data-raw '
		{
			"addressCountry": "United States",
			"addressLocality": "Diamond Bar",
			"addressRegion": "California",
			"addressType": "shipping",
			"name": "Baker Address",
			"postalCode": "12345",
			"primary": false,
			"streetAddressLine1": "789 Goo Rd",
			"streetAddressLine2": "",
			"streetAddressLine3": ""
		}' \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "test@liferay.com:learn"

PostalAddress_PUT_ById.java

Command:

java -classpath .:* -DpostalAddressId=1234 PostalAddress_PUT_ById

Code:

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

	PostalAddressResource postalAddressResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	PostalAddress postalAddress = postalAddressResource.putPostalAddress(
		Long.valueOf(System.getProperty("postalAddressId")),
		new PostalAddress() {
			{
				addressCountry = "United States";
				addressLocality = "Diamond Bar";
				addressRegion = "California";
				addressType = "shipping";
				name = "Dog Address";
				postalCode = "67890";
				primary = false;
				streetAddressLine1 = "789 Goo Rd";
				streetAddressLine2 = "";
				streetAddressLine3 = "";
			}
		});

	System.out.println(postalAddress);
}

Delete a Postal Address

Delete an existing postal address with the following cURL or Java command. Replace 1234 with the postal address’s ID.

PostalAddress_DELETE_ById.sh

Command:

./PostalAddress_DELETE_ById.sh 1234

Code:

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

PostalAddress_DELETE_ById.java

Command:

java -classpath .:* -DpostalAddressId=1234 PostalAddress_DELETE_ById

Code:

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

	PostalAddressResource postalAddressResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	postalAddressResource.deletePostalAddress(
		Long.valueOf(System.getProperty("postalAddressId")));
}

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

Note

On Liferay DXP 2024.Q4+/GA129+, you can use external reference codes to GET/PUT/PATCH/DELETE postal addresses.

Capability: