Using Nested Fields with REST APIs

Available Liferay 7.4 U69+/GA69+

With custom object APIs, you can use the nestedFields parameter to return multiple levels of related objects in a single GET request. The nestedFieldsDepth parameter determines the depth of object entries included in the query: 0-5.

tip

The nestedFields parameter is a convenient way to retrieve information that would usually require multiple requests. With it, you can retrieve an entry along with its related entries. To return only the related entries, Liferay provides dedicated relationship APIs. See Using Relationship REST APIs for an introduction.

To proceed, set up a new Liferay 7.4 instance and prepare the provided tutorial code. Then, run the scripts to create related entries and query them using the nestedFields parameter.

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.75-ga75

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.

Next, 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 name 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 commands below 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 site and company objects, see Objects 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). Click REST Applications and select an API.

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-w4s7/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=ableToBaker,bakerToCharlie&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., ableToBaker,bakerToCharlie).

nestedFieldsDepth: Determines the depth of entries you want to include and can be set between 0-5.