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

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. 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 "[e-mail]: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 "[e-mail]: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 "[e-mail]:learn"
   
   	curl \
   		-H "Content-Type: application/json" \
   		-X POST \
   		"http://localhost:8080/o/object-admin/v1.0/object-definitions/${student}/publish" \
   		-u "[e-mail]:learn"
   

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

3. 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 "[e-mail]: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 "[e-mail]:learn"
   

4. Navigate to Global Menu () → Control Panel → Objects. Click on the Course object that was just created.

5. Click the Relationships tab. Click Add ().

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

7. Click the Details tab. Click Publish.

Adding Sample Courses and Students

1. 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 "[e-mail]: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 "[e-mail]:learn"
   
   	history101=$(curl \
   		-H "Content-Type: application/json" \
   		-X POST \
   	  "http://localhost:8080/o/c/courses" \
   		-d "{\"courseName\": \"History 101\"}" \
   		-u "[e-mail]: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 "[e-mail]:learn"
   

Creating an API Application

1. Navigate to Global Menu () → Control Panel → API Builder.

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

3. Click the Schemas tab. Click Add ().

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

5. Click the newly created schema’s Properties tab. Add the Course Name field by clicking on Course Name in the left menu.

   

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

7. Next, click the Endpoints tab. Click Add ().

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

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

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

Related Topics

• Sample API Tutorials
• Consuming APIs