Building a Sample API Application

Liferay DXP 2023.Q4+/Portal 7.4 GA102+ Beta Feature

Important

The API Builder is currently behind a beta feature flag (LPS-178642). API endpoints currently support retrieving and creating collections of entities.

Follow the steps below to see a mock API application example.

Adding Sample Objects and Entries

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 test@liferay.com and the password test. When prompted, change the password to learn.

Then, follow these steps:

On the command line, run the following script to create a Student object.

	student=$(curl \
		-H "Content-Type: application/json" \
		-X POST \
		"http://localhost:8080/o/object-admin/v1.0/object-definitions" \
		-d "{\"label\": {\"en_US\": \"Student\"}, \"name\": \"Student\", \"panelCategoryKey\": \"control_panel.object\", \"pluralLabel\": {\"en_US\": \"Students\"}, \"scope\": \"company\"}" \
	  -u "test@liferay.com:learn" | jq -r ".id")

	curl \
		-H "Content-Type: application/json" \
		-X POST \
		"http://localhost:8080/o/object-admin/v1.0/object-definitions/${student}/object-fields" \
		-d "{\"businessType\": \"Text\", \"label\": {\"en_US\": \"First Name\"}, \"name\": \"firstName\", \"required\": false}" \
		-u "test@liferay.com:learn"

	curl \
		-H "Content-Type: application/json" \
		-X POST \
		"http://localhost:8080/o/object-admin/v1.0/object-definitions/${student}/object-fields" \
		-d "{\"businessType\": \"Text\", \"label\": {\"en_US\": \"Last Name\"}, \"name\": \"lastName\", \"required\": false}" \
		-u "test@liferay.com:learn"

	curl \
		-H "Content-Type: application/json" \
		-X POST \
		"http://localhost:8080/o/object-admin/v1.0/object-definitions/${student}/publish" \
		-u "test@liferay.com:learn"

Navigate to Global Menu () → Control Panel → Objects. Verify that a new Student object was created.

On the command line, run the following script to create a Course object.

	course=$(curl \
		-H "Content-Type: application/json" \
		-X POST \
		"http://localhost:8080/o/object-admin/v1.0/object-definitions" \
		-d "{\"label\": {\"en_US\": \"Course\"}, \"name\": \"Course\", \"panelCategoryKey\": \"control_panel.object\", \"pluralLabel\": {\"en_US\": \"Courses\"}, \"scope\": \"company\"}" \
		-u "test@liferay.com:learn" | jq -r ".id")

	curl \
		-H "Content-Type: application/json" \
		-X POST \
		"http://localhost:8080/o/object-admin/v1.0/object-definitions/${course}/object-fields" \
		-d "{\"businessType\": \"Text\", \"label\": {\"en_US\": \"Course Name\"}, \"name\": \"courseName\", \"required\": false}" \
	  -u "test@liferay.com:learn"

Navigate to Global Menu () → Control Panel → Objects. Click on the Course object that was just created.
Click the Relationships tab. Click Add ().
Enter the following values to define the new relationship.

Field Value

Label Enrollment

Name enrollment

Type One to Many

One Record Of Course

Many Records of Student

Click Save.
Click the Details tab. Click Publish.

Field	Value
Label	Enrollment
Name	enrollment
Type	One to Many
One Record Of	Course
Many Records of	Student

Adding Sample Courses and Students

On the command line, run the following script to create two courses and two students.

	math101=$(curl \
		-H "Content-Type: application/json" \
		-X POST \
		"http://localhost:8080/o/c/courses" \
		-d "{\"courseName\": \"Math 101\"}" \
		-u "test@liferay.com:learn" | jq -r ".id")

	curl \
		-H "Content-Type: application/json" \
		-X POST \
		"http://localhost:8080/o/c/students" \
		-d "{\"r_enrollment_c_courseId\":${math101}, \"firstName\": \"Mary\", \"lastName\": \"Liferay\"}" \
		-u "test@liferay.com:learn"

	history101=$(curl \
		-H "Content-Type: application/json" \
		-X POST \
	  "http://localhost:8080/o/c/courses" \
		-d "{\"courseName\": \"History 101\"}" \
		-u "test@liferay.com:learn" | jq -r ".id")

	curl \
		-H "Content-Type: application/json" \
		-X POST \
		"http://localhost:8080/o/c/students" \
		-d "{\"r_enrollment_c_courseId\":${history101}, \"firstName\": \"John\", \"lastName\": \"Liferay\"}" \
		-u "test@liferay.com:learn"

Creating an API Application

Navigate to Global Menu () → Control Panel → API Builder.
Click Add (). Enter the title, URL, and description for the new API application.

Field Value

Title Registration

URL registration

Description An API to get student registrations.

Click Create.
Click the Schemas tab. Click Add ().
Enter the name, description, and object for the new schema.

Field Value

Name Course Registrations

Description A list of courses and the students taking them.

Object Course

Click Create.
Click the newly created schema’s Properties tab. Add the Course Name field by clicking on Course Name in the left menu.
In the left menu, click View Related Objects. Click Student to expand the attributes. Add the First Name and Last Name fields by clicking on First Name and Last Name in the left menu. Click Save in the top right corner.
Next, click the Endpoints tab. Click Add ().
Enter the scope, path, and description for the new API endpoint.

Field Value

Scope Company

Path courses

Description An endpoint to get a list of courses and its students.

Click Create.
Click the Configuration tab in the newly created API endpoint. Under Response Body Schema, select the Course Registrations schema you created in the previous step. Click Publish in the top right of the page.
Test out the new API application by navigating to the API explorer (e.g. http://localhost:8080/o/api?endpoint=http://localhost:8080/o/c/registration/openapi.json).

Click the GET courses endpoint and click Execute.

The custom API application returns a list of courses and the students taking the courses.