Managing Objects with Headless APIs

Liferay 7.4+

You can create and manage objects from the Applications menu, but you can also use Liferay’s REST APIs. Call these services to create and manage objects. Note that in Liferay’s codebase, objects are called object definitions. Each object definition is made up of various object fields.

Adding an Object Definition and Object Field

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 [e-mail] and the password test. When prompted, change the password to learn.

Then, follow these steps:

1. Download and unzip the provided sample code:

   curl https://resources.learn.liferay.com/dxp/latest/en/building-applications/objects/creating-and-managing-objects/liferay-r4g6.zip -O
   

   unzip liferay-r4g6.zip
   

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

   ./ObjectDefinition_POST_ToInstance.sh
   

   The JSON response shows a new object definition has been added:

   "active" : false,
   "dateCreated" : "2023-05-31T16:51:18Z",
   "dateModified" : "2023-05-31T16:51:18Z",
   "defaultLanguageId" : "en_US",
   "enableCategorization" : true,
   "enableComments" : false,
   "enableObjectEntryHistory" : false,
   "externalReferenceCode" : "4574eea8-03e9-d4c6-b9f9-23368b94350c",
   "id" : 44525,
   "label" : {
     "en_US" : "Foo"
   },
   "name" : "Foo",
   "objectActions" : [ ],
   ...
   "pluralLabel" : {
     "en_US" : "Foos"
   },
   "portlet" : false,
   "restContextPath" : "/o/c/foos",
   "scope" : "company",
   "status" : {
      "code" : 2,
      "label" : "draft",
      "label_i18n" : "Draft"
   },
   "system" : false,
   "titleObjectFieldName" : "id"
   

3. Navigate to Global Menu → Applications → Objects. See that a new object has been added.

   

   Click the Foo object. Note the object’s ID number.

4. Use the cURL script to add a new object field to the object definition. On the command line, execute the ObjectField_POST_ToObjectDefinition.sh script. Replace 1234 with your object’s ID.

   ./ObjectField_POST_ToObjectDefinition.sh 1234
   

5. In Liferay, click again on the Foo object. Click the Fields tab. Note that a new Able field was added.

   

6. The REST services 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
   

7. Run the ObjectDefinition_POST_ToInstance.java class:

   java -classpath .:* ObjectDefinition_POST_ToInstance
   

8. Note the Foo object’s ID number. Then run the ObjectField_POST_ToObjectDefinition.java class. Replace 1234 with your object’s ID.

   java -classpath .:* -DobjectDefinitionId=1234 ObjectField_POST_ToObjectDefinition
   

Newly created objects are still in draft status. Make your necessary changes or modifications before publishing. Once objects are published, edits are disabled. See publishing object drafts to learn more.

Examine cURL Command

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

curl \
	"http://localhost:8080/o/object-admin/v1.0/object-definitions" \
	--data-raw '
		{
			"label": {
				"en_US": "Foo"
			},
			"name": "Foo",
			"pluralLabel": {
				"en_US": "Foos"
			},
			"scope": "company"
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "[e-mail]:learn"

Here are the command’s arguments:

Arguments	Description
-H "Content-Type: application/json"	Defines a request body format of JSON.
-X POST	The HTTP method to invoke at the specified endpoint
"http://localhost:8080/o/object-admin/v1.0/object-definitions"	The REST service endpoint
-d "{\"label\": {\"en_US\": \"Foo\"}, \"name\": \"Foo\", \"pluralLabel\": {\"en_US\": \"Foos\"}, \"scope\": \"company\"}"	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 ObjectDefinition_POST_ToInstance.java class adds an object definition by calling the related service.

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

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

	ObjectDefinition objectDefinition =
		objectDefinitionResource.postObjectDefinition(
			new ObjectDefinition() {
				{
					label = Collections.singletonMap("en_US", "Foo");
					name = "Foo";
					pluralLabel = Collections.singletonMap("en_US", "Foos");
					scope = "company";
				}
			});

	System.out.println(objectDefinition);
}

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

Line (abbreviated)	Description
ObjectDefinitionResource.Builder builder = ...	Gets a Builder for generating a ObjectDefinitionResource service instance.
ObjectDefinitionResource objectDefinitionResource = builder.authentication(...).build();	Specifies basic authentication and generates a ObjectDefinitionResource service instance.
ObjectDefinition objectDefinition = objectDefinitionResource.postObjectDefinition(...);	Calls the objectDefinitionResource.postObjectDefinition method and passes the data to post.

Note that the project includes the com.liferay.object.admin.rest.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 methods.

Important

See ObjectDefinitionResource for service details.

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

Get Objects from Instance

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

ObjectDefinitions_GET_FromInstance.sh

Command:

./ObjectDefinitions_GET_FromInstance.sh

Code:

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

ObjectDefinitions_GET_FromInstance.java

Command:

java -classpath .:* ObjectDefinitions_GET_FromInstance

Code:

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

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

	Page<ObjectDefinition> page =
		objectDefinitionResource.getObjectDefinitionsPage(
			null, null, null, Pagination.of(1, 2), null);

	System.out.println(page);
}

The Instance’s object definitions appear in JSON.

Get an Object Definition

Get a specific object definition with the following cURL or Java command.

Tip

Use ObjectDefinitions_GET_FromInstance.[java|sh] to get instance ObjectDefinition IDs.

ObjectDefinition_GET_ById.sh

Command:

./ObjectDefinition_GET_ById.sh 1234

Code:

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

ObjectDefinition_GET_ById.java

Command:

java -classpath .:* -DobjectDefinitionId=1234 ObjectDefinition_GET_ById

Code:

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

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

	System.out.println(
		objectDefinitionResource.getObjectDefinition(
			Long.valueOf(System.getProperty("objectDefinitionId"))));
}

The object definition’s fields appear in JSON.

Patch an Object Definition

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

ObjectDefinition_PATCH_ById.sh

Command:

./ObjectDefinition_PATCH_ById.sh 1234

Code:

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

ObjectDefinition_PATCH_ById.java

Command:

java -classpath .:* -DobjectDefinitionId=1234 ObjectDefinition_PATCH_ById

Code:

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

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

	ObjectDefinition objectDefinition =
		objectDefinitionResource.patchObjectDefinition(
			Long.valueOf(System.getProperty("objectDefinitionId")),
			new ObjectDefinition() {
				{
					label = Collections.singletonMap("en_US", "Bar");
					name = "Bar";
					pluralLabel = Collections.singletonMap("en_US", "Bars");
				}
			});

	System.out.println(objectDefinition);
}

Put an Object Definition

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

ObjectDefinition_PUT_ById.sh

Command:

./ObjectDefinition_PUT_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/object-admin/v1.0/object-definitions/${1}" \
	--data-raw '
		{
			"label": {
				"en_US": "Goo"
			},
			"name": "Goo",
			"pluralLabel": {
				"en_US": "Goos"
			},
			"scope": "company"
		}' \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "[e-mail]:learn"

ObjectDefinition_PUT_ById.java

Command:

java -classpath .:* -DobjectDefinitionId=1234 ObjectDefinition_PUT_ById

Code:

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

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

	ObjectDefinition objectDefinition =
		objectDefinitionResource.putObjectDefinition(
			Long.valueOf(System.getProperty("objectDefinitionId")),
			new ObjectDefinition() {
				{
					label = Collections.singletonMap("en_US", "Goo");
					name = "Goo";
					pluralLabel = Collections.singletonMap("en_US", "Goos");
					scope = "company";
				}
			});

	System.out.println(objectDefinition);
}

Delete an Object Definition

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

ObjectDefinition_DELETE_ById.sh

Command:

./ObjectDefinition_DELETE_ById.sh 1234

Code:

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

ObjectDefinition_DELETE_ById.java

Command

java -classpath .:* -DobjectDefinitionId=1234 ObjectDefinition_DELETE_ById

Code:

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

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

	objectDefinitionResource.deleteObjectDefinition(
		Long.valueOf(System.getProperty("objectDefinitionId")));
}

Services for Object Fields

The cURL commands and Java classes for object field work in the same way as object definitions.

Files	Description
ObjectField_DELETE_ById.[java\|sh]	Deletes an object field by ID.
ObjectField_GET_ById.[java\|sh]	Gets a specific object field by ID.
ObjectField_PATCH_ById.[java\|sh]	Patches a specific object field by ID.
ObjectField_POST_ToObjectDefinition.[java\|sh]	Posts an object field to an object definition.
ObjectField_PUT_ById.[java\|sh]	Replaces a specific object field by ID.
ObjectFields_GET_FromObjectDefinition.[java\|sh]	Gets a list of object fields from an object definition.

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

Related Topics

• Creating Objects
• Using Liferay as a Headless Platform
• Sample API Tutorials