Accounts API Basics

Liferay DXP/Portal 7.4+

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

Adding an Account

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

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

   unzip liferay-t5p9.zip
   

2. Use the cURL script to add a new Account to your instance. On the command line, navigate to the curl folder. Execute the Account_POST_ToInstance.sh script.

   ./Account_POST_ToInstance.sh
   

   The JSON response shows a new Account has been added:

   {
     "description" : "Foo",
     "domains" : [ ],
     "externalReferenceCode" : "",
     "id" : 39302,
     "name" : "Able",
     "numberOfUsers" : 0,
     "organizationIds" : [ ],
     "parentAccountId" : 0,
     "status" : 0,
     "type" : "business"
   }
   

3. Navigate to Global Menu → Applications → Accounts. See that a new Account has been added.

   

4. 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 with the following command:

   javac -classpath .:* *.java
   

5. Run the Account_POST_ToInstance.java class with the following command.

   java -classpath .:* Account_POST_ToInstance
   

Examine the cURL Command

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

curl \
	"http://localhost:8080/o/headless-admin--userser/v1.0/accounts" \
	--data-raw '
		{
			"description": "Foo",
			"name": "Able"
		}' \
	--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-user/v1.0/accounts"	The REST service endpoint
-d "{\"description\": \"Foo\", \"name\": \"Able\"}"	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 Account_POST_ToInstance.java class adds an account by calling the Account-related service.

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

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

	Account account = accountResource.postAccount(
		new Account() {
			{
				description = "Foo";
				name = "Fox";
			}
		});

	System.out.println(account);
}

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

Line (abbreviated)	Description
AccountResource.Builder builder = ...	Gets a Builder for generating an AccountResource service instance.
AccountResource accountResource = builder.authentication(...).build();	Specifies basic authentication and generates a AccountResource service instance.
Account account = accountResource.postAccount(...);	Calls the accountResource.postAccount 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 AccountResource methods.

Important

See AccountResource for service details.

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

Get Accounts from Instance

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

Accounts_GET_FromInstance.sh

Command:

./Accounts_GET_FromInstance.sh

Code:

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

Accounts_GET_FromInstance.java

Command:

java -classpath .:* Accounts_GET_FromInstance

Code:

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

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

	Page<Account> page = accountResource.getAccountsPage(
		null, null, Pagination.of(1, 2), null);

	System.out.println(page);
}

The Instance’s Account objects appear in JSON.

Get an Account

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

Tip

Use Accounts_GET_FromInstance.[java|sh] to get instance Account IDs.

Account_GET_ById.sh

Command:

./Account_GET_ById.sh 1234

Code:

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

Account_GET_ById.java

Command:

java -classpath .:* -DaccountId=1234 Account_GET_ById

Code:

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

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

	System.out.println(
		accountResource.getAccount(
			Long.valueOf(System.getProperty("accountId"))));
}

The Account fields appear in JSON.

Patch an Account

Do a partial edit of an existing Account with the following cURL and Java commands. Note, replace 1234 with your Account’s ID.

Account_PATCH_ById.sh

Command:

./Account_PATCH_ById.sh 1234

Code:

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

Account_PATCH_ById.java

Command:

java -classpath .:* -DaccountId=1234 Account_PATCH_ById

Code:

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

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

	Account account = accountResource.patchAccount(
		Long.valueOf(System.getProperty("accountId")),
		new Account() {
			{
				description = "Bar";
			}
		});

	System.out.println(account);
}

Put an Account

Completely overwrite an existing Account with the following cURL and Java commands. Note, replace 1234 with your Account’s ID.

Account_PUT_ById.sh

Command:

./Account_PUT_ById.sh 1234

Code:

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

Account_PUT_ById.java

Command:

java -classpath .:* -DaccountId=1234 Account_PUT_ById

Code:

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

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

	Account account = accountResource.putAccount(
		Long.valueOf(System.getProperty("accountId")),
		new Account() {
			{
				description = "Goo";
				name = "George";
			}
		});

	System.out.println(account);
}

Delete an Account

Delete an existing Account with the following cURL and Java commands. Note, replace 1234 with your Account’s ID.

Account_DELETE_ById.sh

Command:

./Account_DELETE_ById.sh 1234

Code:

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

Account_DELETE_ById.java

Command

java -classpath .:* -DaccountId=1234 Account_DELETE_ById

Code:

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

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

	accountResource.deleteAccount(
		Long.valueOf(System.getProperty("accountId")));
}

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

Note

Create and get account postal addresses with PostalAddress_POST_ToAccount and PostalAddresses_GET_FromAccount

Related Topics

• Accounts
• OAuth2
• API Explorer