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

  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 "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"
    
  2. Navigate to Global Menu (Global Menu) → Control PanelObjects. 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 "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"
    
  4. Navigate to Global Menu (Global Menu) → Control PanelObjects. Click on the Course object that was just created.

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

  6. Enter the following values to define the new relationship.

    FieldValue
    LabelEnrollment
    Nameenrollment
    TypeOne to Many
    One Record OfCourse
    Many Records ofStudent

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

  1. Navigate to Global Menu (Global Menu) → Control PanelAPI Builder.

  2. Click Add (Add icon). Enter the title, URL, and description for the new API application.

    Create a new API application

    FieldValue
    TitleRegistration
    URLregistration
    DescriptionAn API to get student registrations.

    Click Create.

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

  4. Enter the name, description, and object for the new schema.

    FieldValue
    NameCourse Registrations
    DescriptionA list of courses and the students taking them.
    ObjectCourse

    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.

    Add the course name field to the schema.

  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 (Add icon).

  8. Enter the scope, path, and description for the new API endpoint.

    FieldValue
    ScopeCompany
    Pathcourses
    DescriptionAn 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.

    Execute the Get courses endpoint.

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

Capabilities

Product

Contact Us

Connect

Powered by Liferay
© 2024 Liferay Inc. All Rights Reserved • Privacy Policy