Documentation

Object API Basics

When you publish an Object, Liferay automatically generates REST APIs for it. These APIs differ for Company and Site scoped Objects, but they all use the c/[pluralobjectlabel] naming pattern (e.g., c/timeoffrequests). You can use these APIs to create, access, update, and remove Object entries.

Here you’ll use cURL commands to perform basic CRUD operations for a custom Object. Before proceeding, set up a new Liferay DXP/Portal 7.4 instance and prepare the provided tutorial code.

Tip

For a complete list of APIs generated for both Site and Company Objects, see Object’s Headless Framework Integration. You can view and test custom Object APIs via the Liferay API Explorer at [server]:[port]/o/api (e.g., localhost:8080/o/api). They are listed under REST Applications.

Setting Up a Liferay Instance

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.22-ga22

Sign in to Liferay at http://localhost:8080. Use the email address test@liferay.com and the password test. When prompted, change the password to learn.

Then, follow these steps to create a basic Object for this tutorial:

  1. Open the Global Menu (Global Menu), click the Control Panel tab, and go to Objects.

  2. Click the Add button (Add Button) and enter these values:

    Field

    Value

    Label

    Able

    Plural Label

    Ables

    Name

    Able

  3. Select the new Object draft, go to the Fields tab, and add a single text field:

    Label

    Field Name

    Type

    Required

    Name

    name

    Text

  4. Go to the Details tab and click Publish.

    Important

    For this tutorial, you must use the above values.

Publishing an Object creates and activates a new application for receiving and storing data. You can now access it via Headless APIs.

Preparing the Sample Code

Run the following commands to download and unzip the provided sample code:

curl https://learn.liferay.com/dxp/latest/en/building-applications/objects/objects-tutorials/using-apis/liferay-v1s4.zip -O
unzip liferay-v1s4.zip

These scripts include the following APIs:

HTTP Method

HTTP Endpoint

Description

GET

/

Returns a complete list of Object entries in a Liferay instance; results can be paginated, filtered, searched, and sorted

POST

/

Creates a new Object entry using the details provided in the API call

DELETE

/{objectNameId}

Deletes the specified Object entry and returns a 204 if the operation succeeds

GET

/{objectNameId}

Returns details for the specified Object entry

PUT

/{objectNameId}

Replaces the specified Object entry’s details with those provided in the API call

Calling the Custom Object’s APIs

  1. After downloading the sample code, navigate to the curl folder in the liferay-v1s4 project.

    cd liferay-v1s4/curl
    
  2. Execute Able_POST_ToCompany. This creates three entries.

    ./Able_POST_ToCompany.sh
    

    The terminal displays the complete schema for the newly created entries. Copy the first entry’s ID for use with the following methods.

    {
      "id" : 41969,
      ...
      "name" : "Able 1"
    }
    
    {
      "id" : 41971,
      ...
      "name" : "Able 2"
    }
    
    {
      "id" : 41973,
      ...
      "name" : "Able 3"
    }
    
  3. Execute Ables_GET_FromCompany. This returns a list of the Object’s entries.

    ./Ables_GET_FromCompany.sh
    
  4. Execute Able_PUT_ById with the first entry’s ID as a parameter. This replaces the details of the specified entry with the details provided in the API call.

    ./Able_PUT_ById.sh {entry-id}
    
    {
      "id" : 41969,
      ...
      "name" : "Able One"
    }
    
  5. Execute Able_DELETE_ById with the same ID as its parameter. This deletes the specified entry.

    ./Able_DELETE_ById.sh {entry-id}
    
  6. Execute Able_GET_ById with the same ID as its parameter. This returns the details for the specified entry if it exists.

    ./Able_GET_ById.sh {entry-id}
    

    Since you deleted the entry in the preceding step, it returns the following message.

    {
      "status" : "NOT_FOUND",
      "title" : "No ObjectEntry exists with the primary key 41969"
    }
    

Examining the Sample cURL Scripts

The following are examples of the tutorial’s cURL commands.

Able_POST_ToCompany.sh

curl \
	-H "Content-Type: application/json" \
	-X POST \
	"http://localhost:8080/o/c/ables/" \
	-d "{\"name\": \"Able 1\"}" \
	-u "[email protected]:learn"

curl \
	-H "Content-Type: application/json" \
	-X POST \
	"http://localhost:8080/o/c/ables/" \
	-d "{\"name\": \"Able 2\"}" \
	-u "[email protected]:learn"

curl \
	-H "Content-Type: application/json" \
	-X POST \
	"http://localhost:8080/o/c/ables/" \
	-d "{\"name\": \"Able 3\"}" \
	-u "[email protected]:learn"

Able_PUT_ById.sh

curl \
	-H "Content-Type: application/json" \
	-X PUT \
	"http://localhost:8080/o/c/ables/${1}" \
	-d "{\"name\": \"Able One\"}" \
	-u "[email protected]:learn"