Using Nested Fields with REST APIs¶
With custom Object APIs, you can use the nestedFields
parameter to return multiple levels of related Objects in a single GET request. You can also use the nestedFieldsDepth
parameter to determine the depth of Object entries included in the query: 0-5
. Here you’ll use cURL scripts to call Object APIs with nested fields.
Tip
Nested fields are a convenient way to retrieve information that would usually require multiple requests. This way you can have all the information of a related entity from the entity itself without sending a new request with the related entity id.
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.55-ga55
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 three Objects:
Open the Global Menu (
), go to the Control Panel tab, and click Objects.
Create three Object drafts.
First Object:
Field
Value
Label
Able
Plural Label
Ables
Name
Able
Second Object:
Field
Value
Label
Baker
Plural Label
Bakers
Name
Baker
Third Object:
Field
Value
Label
Charlie
Plural Label
Charlies
Name
Charlie
Add the following text field to each Object draft.
Label
Field Name
Type
Required
Name
name
Text
✔
Define the following relationships.
For Able:
Label
Relationship Name
Type
Object
Able to Baker
ableToBaker
One to Many
Baker
For Baker:
Label
Relationship Name
Type
Object
Baker to Charlie
bakerToCharlie
One to Many
Charlie
Publish each Object.
Once published, you can access each 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-w4s7.zip -O
unzip liferay-w4s7.zip
The sample code includes POST commands for each Object, as well as a GET command for Charlie
.
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.
Using the Sample Code¶
Follow these steps to add and query related Object entries:
Navigate to the
curl
folder in theliferay-w4s7
project.cd liferay-p8n6/curl
Execute
Able_POST_ToCompany
to createAble
entries../Able_POST_ToCompany.sh
Copy the first entry’s ID for use with the following POST command.
{ "id" : 41969, ... "name" : "Able 1" } { "id" : 41971, ... "name" : "Able 2" } { "id" : 41973, ... "name" : "Able 3" }
Execute
Baker_POST_ToCompany
using theAble
entry ID as a parameter../Baker_POST_ToCompany.sh {able-entry-id}
This creates
Baker
entries related to the specifiedAble
entry. Copy the firstBaker
entry ID for use with the following POST command.{ "id" : 41975, ... "name" : "Baker 1" "r_ableToBaker_c_ableId" : 41969 } { "id" : 41977, ... "name" : "Baker 2" "r_ableToBaker_c_ableId" : 41969 } { "id" : 41979, ... "name" : "Baker 3" "r_ableToBaker_c_ableId" : 41969 }
Execute
Charlie_POST_ToCompany
using theBaker
entry ID as a parameter../Charlie_POST_ToCompany.sh {baker-entry-id}
This creates
Charlie
entries related to the precedingBaker
entry. Copy the first entry’s ID for use with the following GET command.{ "id" : 41981, ... "name" : "Charlie 1", "r_bakerToCharlie_c_bakerId" : 41975 } { "id" : 41983, ... "name" : "Charlie 2", "r_bakerToCharlie_c_bakerId" : 41975 } { "id" : 41985, ... "name" : "Charlie 3", "r_bakerToCharlie_c_bakerId" : 41975 }
Execute
Charlie_GET_ById
using theCharlie
entry ID as a parameter../Charlie_GET_ById.sh [charlie-entry-id]
This queries the entry using nested fields and returns the schema for all three levels of the related Objects.
{ "r_bakerToCharlie_c_baker" : { ... "id" : 41975, ... "r_ableToBaker_c_able" : { ... "id" : 41969, ... "name" : "Able 1" }, "name" : "Baker 1", "r_ableToBaker_c_ableId" : 41969 }, "name" : "Charlie 1", "r_bakerToCharlie_c_bakerId" : 41975 }
Examining the GET Script¶
curl \
"http://localhost:8080/o/c/charlies/${1}/?nestedFields=able,baker&nestedFieldsDepth=2" \
-u "[email protected]:learn"
The provided GET method calls a URL with the nestedFields
and nestedFieldsDepth
parameters.
nestedFields
: Determines the types of entries included in the query (e.g., able,baker
).
nestedFieldsDepth
: Determines the depth of entries you want to include and can be set between 0-5.