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
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.
Next, prepare the sample code:
-
Download and unzip Picklists API Basics.
-
Use the cURL script to add a new picklist to your instance. On the command line, navigate to the
curl
folder. Execute theListTypeDefinition_POST_ToInstance.sh
script.The JSON response shows a new picklist has been added:
-
Navigate to Global Menu → Control Panel → Picklists. The new picklist appears.
-
Alternatively, you can call the REST service using the Java client. Navigate into the
java
folder and compile the source files: -
Run the
ListTypeDefinition_POST_ToInstance.java
class:
Examine the cURL Command
The ListTypeDefinition_POST_ToInstance.sh
script calls the REST service using cURL.
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 "test@liferay.com:learn" | Basic authentication credentials |
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 ListTypeDefinition_POST_ToInstance.java
class adds a picklist by calling the ListType
-related services.
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).
The main
method’s comment demonstrates running the class.
The other Java classes similarly call different ListTypeDefinitionResource
methods.
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:
Code:
ListTypeDefinitions_GET_FromInstance.java
Command:
Code:
The Instance’s Picklist
objects appear in JSON.
Get a Picklist
Get a specific picklist with the following cURL or Java command.
Use ListTypeDefinitions_GET_FromInstance.[java|sh]
to get instance Picklist
IDs.
ListTypeDefinition_GET_ById.sh
Command:
Code:
ListTypeDefinition_GET_ById.java
Command:
Code:
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.
ListTypeDefinition_PATCH_ById.sh
Command:
Code:
ListTypeDefinition_PATCH_ById.java
Command:
Code:
Put a Picklist
Completely overwrite an existing picklist with cURL and Java put
commands. Replace 1234
with your picklist’s ID.
ListTypeDefinition_PUT_ById.sh
Command:
Code:
ListTypeDefinition_PUT_ById.java
Command:
Code:
Delete a Picklist
Delete an existing picklist with cURL and Java delete
commands. Replace 1234
with your picklist’s ID.
ListTypeDefinition_DELETE_ById.sh
Command:
Code:
ListTypeDefinition_DELETE_ById.java
Command
Code:
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. |
ListTypeEntry_DELETE_ById.[java\|sh] | Delete a picklist entry. |
ListTypeEntry_GET_ById[java\|sh] | Get a specific picklist entry by ID. |
ListTypeEntry_POST_ToListTypeDefinition.[java\|sh] | Post an entry to a picklist. |
ListTypeEntry_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.