Using Batch APIs

When you publish an Object, Liferay automatically generates REST APIs for it. These include the batch APIs for bulk POST, PUT, and DELETE operations. Here you’ll use cURL commands to call these batch APIs 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 appear 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.112-ga112

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), go to the Control Panel tab, and click Objects.

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

    FieldValue
    LabelAble
    Plural LabelAbles
    NameAble
  3. Select the new Object draft, go to the Fields tab, and add a single text field:

    LabelField NameTypeRequired
    NamenameText
  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://resources.learn.liferay.com/dxp/latest/en/building-applications/objects/understanding-object-integrations/using-custom-object-apis/liferay-t4r3.zip -O
unzip liferay-t4r3.zip

These scripts include the following batch APIs:

HTTP MethodHTTP EndpointDescription
DELETE/batchDeletes multiple Object entries
POST/batchCreates multiple Object entries using the details provided in the API call
PUT/batchReplaces multiple Object entries using the details provided in the API call
Note

The GET method is included for demonstration purposes. This returns a complete list of Object entries in a Liferay instance.

Calling the Custom Object’s APIs

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

    cd liferay-t4r3/curl
    
  2. Execute Ables_POST_Batch. This creates multiple Object entries.

    ./Ables_POST_Batch.sh
    

    The terminal shows a similar output.

    {
      "className" : "com.liferay.object.rest.dto.v1_0.ObjectEntry",
      "contentType" : "JSON",
      "errorMessage" : "",
      "executeStatus" : "INITIAL",
      "externalReferenceCode" : "",
      "failedItems" : [ ],
      "id" : 4,
      "importStrategy" : "ON_ERROR_FAIL",
      "operation" : "CREATE",
      "processedItemsCount" : 0,
      "startTime" : "2022-04-07T22:51:37Z",
      "totalItemsCount" : 0
    }
    
  3. Run Ables_GET_FromCompany to verify the entries were created. This returns a list of all Object entries.

    ./Ables_GET_FromCompany.sh
    

    Copy each entry’s ID for use with the following PUT and DELETE methods.

    {
      ...
      "items" : [ {
        ...
        "id" : 41985,
        ...
        "name" : "Able 1"
      }, {
        ...
        "id" : 41987,
        ...
        "name" : "Able 2"
      }, {
        ...
        "id" : 41989,
        ...
        "name" : "Able 3"
      } ],
      "lastPage" : 1,
      "page" : 1,
      "pageSize" : 20,
      "totalCount" : 3
    }
    
  4. Execute Ables_PUT_Batch with each entry ID as a parameter. This replaces the details of the specified entry with the details provided in the API call.

    ./Ables_PUT_Batch.sh {first-entry-id} {second-entry-id} {third-entry-id}
    
    {
      "className" : "com.liferay.object.rest.dto.v1_0.ObjectEntry",
      "contentType" : "JSON",
      "errorMessage" : "",
      "executeStatus" : "INITIAL",
      "externalReferenceCode" : "",
      "failedItems" : [ ],
      "id" : 6,
      "importStrategy" : "ON_ERROR_FAIL",
      "operation" : "UPDATE",
      "processedItemsCount" : 0,
      "startTime" : "2022-04-07T23:02:17Z",
      "totalItemsCount" : 0
    }
    
  5. Run Ables_GET_FromCompany to verify the entries were updated.

    ./Ables_GET_FromCompany.sh
    
    {
      ...
      "items" : [ {
        ...
        "id" : 41985,
        ...
        "name" : "Able One"
      }, {
        ...
        "id" : 41987,
        ...
        "name" : "Able Two"
      }, {
        ...
        "id" : 41989,
        ...
        "name" : "Able Three"
      } ],
      "lastPage" : 1,
      "page" : 1,
      "pageSize" : 20,
      "totalCount" : 3
    }
    
  6. Execute Ables_DELETE_Batch with each entry ID as a parameter. This deletes the specified entries.

    ./Ables_DELETE_Batch.sh {first-entry-id} {second-entry-id} {third-entry-id}
    
  7. Run Ables_GET_FromCompany to verify the entries were deleted.

    ./Ables_GET_FromCompany.sh
    

    Since you deleted the entries in the preceding step, it returns an entries NOT FOUND error.

Examining the Sample cURL Scripts

Ables_POST_Batch.sh

curl \
	"http://localhost:8080/o/c/ables/batch" \
	--data-raw '
		[
			{
				"name": "Able 1"
			},
			{
				"name": "Able 2"
			},
			{
				"name": "Able 3"
			}
		]' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"

Ables_PUT_Batch.sh

curl \
	"http://localhost:8080/o/c/ables/batch" \
	--data-raw '
		[
			{
				"id": "'"${1}"'",
				"name": "Able One"
			},
			{
				"id": "'"${2}"'",
				"name": "Able Two"
			},
			{
				"id": "'"${3}"'",
				"name": "Able Three"
			}
		]' \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "test@liferay.com:learn"

Ables_DELETE_Batch.sh

curl \
	"http://localhost:8080/o/c/ables/batch" \
	--data-raw '
		[
			{
				"id": "'"${1}"'"
			},
			{
				"id": "'"${2}"'"
			},
			{
				"id": "'"${3}"'"
			}
		]' \
	--header "Content-Type: application/json" \
	--request "DELETE" \
	--user "test@liferay.com:learn"

Capabilities

Product

Contact Us

Connect

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