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.q1.1

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 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

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"

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

Click the Foo object. Note the object’s ID number.
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
```
In Liferay, click again on the Foo object. Click the Fields tab. Note that a new Able field was added.
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
```

Run the ObjectDefinition_POST_ToInstance.java class:

java -classpath .:* ObjectDefinition_POST_ToInstance

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 "test@liferay.com: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 "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 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(
			"test@liferay.com", "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 "test@liferay.com: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(
			"test@liferay.com", "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 "test@liferay.com: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(
			"test@liferay.com", "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 "test@liferay.com: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(
			"test@liferay.com", "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 "test@liferay.com: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(
			"test@liferay.com", "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 "test@liferay.com: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(
			"test@liferay.com", "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.

Capability:

Development and Tooling

Deployment Approach:

Liferay PaaS

Liferay SaaS

Liferay Self-Hosted

Feature:

Objects

Cloud

Commerce

Content Management System

Development and Tooling

Digital Asset Management

DXP Self-Hosted Installation, Maintenance, and Administration

Integration

Personalization

Platform

Search

Security

Sites

Analytics Cloud

Commerce

DXP

Liferay Cloud

Reference