Documentation

Documentation Menu
Go Back

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.29-ga29

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:

  1. Open the Global Menu (Global Menu), click the Control Panel tab, and go to Objects.

  2. 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

  3. Add the following text field to each Object draft.

    Label

    Field Name

    Type

    Required

    Name

    name

    Text

    ✔

  4. 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

  5. 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:

  1. Navigate to the curl folder in the liferay-w4s7 project.

    cd liferay-p8n6/curl

  2. 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"
}

  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
}

  4. 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
}

  5. 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.

Not finding what you're looking for?

Pardon our dust as we revamp and transition our product documentation to this site. If something seems missing, please check Liferay Help Center documentation for Liferay DXP 7.2 and previous versions.

Try Liferay's Help Center