Picklists API Basics

Liferay provides the headless-admin-list-types REST APIs for creating and managing picklist definitions (ListTypeDefinition) and their entries (ListTypeEntry). You can view and test available APIs in Liferay’s API Explorer at [server]:[port]/o/api (e.g., localhost:8080/o/api) under the REST Services menu.

Call the headless-admin-list-types services to create and manage picklists.

Adding a Picklist

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:2025.q1.6-lts

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.

Next, prepare the sample code:

1. Download and unzip Picklists API Basics.

   curl https://resources.learn.liferay.com/examples/liferay-v3n6.zip -O
   

   unzip liferay-v3n6.zip
   

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

   ./ListTypeDefinitions_POST_ToInstance.sh
   

   The JSON response shows a new picklist has been added:

   "dateCreated" : "2022-11-17T18:42:13Z",
   "dateModified" : "2022-11-17T18:42:13Z",
   "id" : 47502,
   "listTypeEntries" : [ ],
   "name" : "Foo",
   "name_i18n" : {
      "en-US" : "Foo"
   }
   

3. Navigate to Global Menu → Control Panel → Picklists. The new picklist appears.

   

4. Alternatively, you can call the REST service using the Java client. Navigate into the java folder and compile the source files:

   javac -classpath .:* *.java
   

5. Run the ListTypeDefinitions_POST_ToInstance.java class:

   java -classpath .:* ListTypeDefinitions_POST_ToInstance
   

Examine the cURL Command

The ListTypeDefinitions_POST_ToInstance.sh script calls the REST service using cURL.

curl \
	"http://localhost:8080/o/headless-admin-list-type/v1.0/list-type-definitions" \
	--data-raw '
		{
			"name": "Foo",
			"name_i18n": {
				"en_US": "Foo"
			}
		}' \
	--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-list-type/v1.0/list-type-definitions"	The REST service endpoint
-d "{\"name\": \"Foo\", \"name_i18n\": {\"en_US\": \"Foo\"}}"	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.

The other cURL commands use similar JSON arguments.

Examine the Java Class

The ListTypeDefinitions_POST_ToInstance.java class adds a picklist by calling the ListType-related services.

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

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

	ListTypeDefinition listTypeDefinition =
		listTypeDefinitionResource.postListTypeDefinition(
			new ListTypeDefinition() {
				{
					name = "Foo";
					name_i18n = Collections.singletonMap("en_US", "Foo");
				}
			});

	System.out.println(listTypeDefinition);
}

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

Line (abbreviated)	Description
ListTypeDefinitionResource.Builder builder = ...	Gets a Builder for generating an ListTypeDefinitionResource service instance.
ListTypeDefinitionResource listTypeDefinitionResource = builder.authentication(...).build();	Specifies basic authentication and generates a ListTypeDefinitionResource service instance.
ListTypeDefinition listTypeDefinitionResource = listTypeDefinitionResource.postListTypeDefinition(...);	Calls the listTypeDefinitionResource.postListTypeDefinition method and passes the data to post.

Note that the project includes the com.liferay.headless.admin.list.type.client file as a dependency. You can find client JAR dependency information for all REST applications in your installation’s API explorer at /o/api (e.g., http://localhost:8080/o/api).

Note

The main method’s comment demonstrates running the class.

The other Java classes similarly call different ListTypeDefinitionResource methods.

Important

See ListTypeDefinitionResource for service details.

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

Get Picklists from Instance

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

ListTypeDefinitions_GET_FromInstance.sh

Command:

./ListTypeDefinitions_GET_FromInstance.sh

Code:

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

ListTypeDefinitions_GET_FromInstance.java

Command:

java -classpath .:* ListTypeDefinitions_GET_FromInstance

Code:

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

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

	Page<ListTypeDefinition> page =
		listTypeDefinitionResource.getListTypeDefinitionsPage(
			null, null, null, Pagination.of(1, 2), null);

	System.out.println(page);
}

The Instance’s Picklist objects appear in JSON.

Get a Picklist

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

Tip

Use ListTypeDefinitions_GET_FromInstance.[java|sh] to get instance Picklist IDs.

ListTypeDefinitions_GET_ById.sh

Command:

./ListTypeDefinitions_GET_ById.sh 1234

Code:

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

ListTypeDefinitions_GET_ById.java

Command:

java -classpath .:* -DlistTypeDefinitionId=1234 ListTypeDefinitions_GET_ById

Code:

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

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

	System.out.println(
		listTypeDefinitionResource.getListTypeDefinition(
			Long.valueOf(System.getProperty("listTypeDefinitionId"))));
}

The Picklist fields appear in JSON.

Patch a Picklist

Edit an existing picklist with cURL and Java patch commands. Replace 1234 with your picklist’s ID.

ListTypeDefinitions_PATCH_ById.sh

Command:

./ListTypeDefinitions_PATCH_ById.sh 1234

Code:

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

ListTypeDefinitions_PATCH_ById.java

Command:

java -classpath .:* -DlistTypeDefinitionId=1234 ListTypeDefinitions_PATCH_ById

Code:

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

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

	ListTypeDefinition listTypeDefinition =
		listTypeDefinitionResource.patchListTypeDefinition(
			Long.valueOf(System.getProperty("listTypeDefinitionId")),
			new ListTypeDefinition() {
				{
					name = "Bar";
					name_i18n = Collections.singletonMap("en_US", "Bar");
				}
			});

	System.out.println(listTypeDefinition);
}

Put a Picklist

Completely overwrite an existing picklist with cURL and Java put commands. Replace 1234 with your picklist’s ID.

ListTypeDefinitions_PUT_ById.sh

Command:

./ListTypeDefinitions_PUT_ById.sh 1234

Code:

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

ListTypeDefinitions_PUT_ById.java

Command:

java -classpath .:* -DlistTypeDefinitionId=1234 ListTypeDefinitions_PUT_ById

Code:

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

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

	ListTypeDefinition listTypeDefinition =
		listTypeDefinitionResource.putListTypeDefinition(
			Long.valueOf(System.getProperty("listTypeDefinitionId")),
			new ListTypeDefinition() {
				{
					name = "Goo";
					name_i18n = Collections.singletonMap("en_US", "Goo");
				}
			});

	System.out.println(listTypeDefinition);
}

Delete a Picklist

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

ListTypeDefinitions_DELETE_ById.sh

Command:

./Picklist_DELETE_ById.sh 1234

Code:

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

ListTypeDefinitions_DELETE_ById.java

Command

java -classpath .:* -DlistTypeDefinitionId=1234 ListTypeDefinitions_DELETE_ById

Code:

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

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

	listTypeDefinitionResource.deleteListTypeDefinition(
		Long.valueOf(System.getProperty("listTypeDefinitionId")));
}

Picklist Entry Services

After creating a picklist, use the services below to create and manage picklist entries. The cURL commands and Java classes for ListTypeEntry work like ListTypeDefinition. Some services require passing the picklist ID.

Files	Description
ListTypeEntries_GET_FromListTypeDefinition.[java\|sh]	Get a list of picklist entries from a picklist.
ListTypeEntries_DELETE_ById.[java\|sh]	Delete a picklist entry.
ListTypeEntries_GET_ById[java\|sh]	Get a specific picklist entry by ID.
ListTypeEntries_POST_ToListTypeDefinition.[java\|sh]	Post an entry to a picklist.
ListTypeEntries_PUT_ById.[java\|sh]	Put a picklist entry.

The API Explorer shows all ListTypeDefinition and ListTypeEntry services and schemas and has an interface to test each service.

Related Topics

• Creating Picklists
• Exporting and Importing Picklists