Documentation

Using Aggregation Terms with REST APIs

When querying Object entries using REST APIs, you can use an Object’s fields as facet criteria for aggregating entry data. To do this, add the aggregationTerms parameter to your GET request and specify the data fields you want to use as facet criteria. These criteria can include custom fields, default metadata fields, or relationship fields. The request response then groups the specified data facets into a single facets block.

Here you’ll use the aggregatedTerms parameter with a basic custom Object.

Before proceeding, set up a new Liferay DXP/Portal 7.4 instance and prepare the provided tutorial code.

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 the following text fields:

    Label

    Field Name

    Type

    Required

    Name

    name

    Text

    Description

    description

    Text

  4. Go to the Details tab and click Publish.

    Important

    For this tutorial, you must use the above values.

Once published, you can access the Object 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-b3x5.zip -O
unzip liferay-b3x5.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

/batch

Creates multiple Object entries using the details provided in the API call

Using the Sample Code

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

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

    ./Ables_POST_Batch.sh
    

    The terminal should display a similar output.

    {
      "className" : "com.liferay.object.rest.dto.v1_0.ObjectEntry",
      "contentType" : "JSON",
      "errorMessage" : "",
      "executeStatus" : "STARTED",
      "externalReferenceCode" : "",
      "failedItems" : [ ],
      "id" : 1,
      "importStrategy" : "ON_ERROR_FAIL",
      "operation" : "CREATE",
      "processedItemsCount" : 0,
      "startTime" : "2022-04-27T00:18:23Z",
      "totalItemsCount" : 0
    }
    
  3. Run Ables_GET_FromCompany to return a list of all created entries with the aggregatedTerms parameter.

    The response should include a facets block with two facet criteria, dateModified and description.

    ...
    "facets" : [ {
        "facetCriteria" : "dateModified",
        "facetValues" : [ {
          "numberOfOccurrences" : 3,
          "term" : "20220427001823"
        } ]
      }, {
        "facetCriteria" : "description",
        "facetValues" : [ {
          "numberOfOccurrences" : 1,
          "term" : "bar"
        }, {
          "numberOfOccurrences" : 1,
          "term" : "foo"
        }, {
          "numberOfOccurrences" : 1,
          "term" : "goo"
        } ]
    } ],
    ...
    

    This block is followed by the standard GET response.

    {
      ...
      "id" : 41969,
      ...
      "name" : "Able 1",
      "description" : "Foo"
      ...
    }, {
      ...
      "id" : 41971,
      ...
      "name" : "Able 2",
      "description" : "Bar"
    }, {
      ...
      "id" : 41973,
      ...
      "name" : "Able 3",
      "description" : "Goo"
    }
    ...
    

Examining the Code

curl \
	"http://localhost:8080/o/c/ables/?aggregationTerms=dateModified,description" \
	-u "[email protected]:learn"

This batch GET method includes the aggregationTerms URL parameter with two values: dateModified and description. These determine the facet criteria used for aggregating data from Object entries in the request response.