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 [email protected] 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://resources.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 the liferay-w4s7 project.
```
cd liferay-p8n6/curl
```

Execute Able_POST_ToCompany to create Able 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 the Able entry ID as a parameter.

./Baker_POST_ToCompany.sh {able-entry-id}

This creates Baker entries related to the specified Able entry. Copy the first Baker 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 the Baker entry ID as a parameter.

./Charlie_POST_ToCompany.sh {baker-entry-id}

This creates Charlie entries related to the preceding Baker 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 the Charlie 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.

Using Nested Fields with REST APIs

Setting Up a Liferay Instance

Preparing the Sample Code

Using the Sample Code

Examining the GET Script

Additional Information

Not finding what you're looking for?