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 system 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.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:
-
Open the Global Menu (), go to the Control Panel tab, and click Objects.
-
Click the Add button () and enter these values:
Field Value Label Able
Plural Label Ables
Name Able
-
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 -
Go to the Details tab and click Publish.
ImportantFor 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://resources.learn.liferay.com/dxp/latest/en/building-applications/objects/understanding-object-integrations/using-custom-object-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
-
After downloading the sample code, navigate to the
curl
folder in theliferay-b3x5
project.cd liferay-b3x5/curl
-
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 }
-
Run
Ables_GET_FromCompany
to return a list of all created entries with theaggregatedTerms
parameter.The response should include a
facets
block with two facet criteria,dateModified
anddescription
.... "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" \
--user "test@liferay.com: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.