Using Relationship REST APIs

Liferay 7.4 U70+/GA70+

When you add relationships to custom or system objects, Liferay generates REST endpoints for accessing those relationships. You can relate and disassociate entries, as well as return an entry’s related entries. These endpoints are added to the parent object in one-to-many relationships and to both objects in many-to-many relationships.

To proceed, set up a new Liferay 7.4 instance and prepare the provided tutorial code. Then, run the scripts to create object entries and manage their relationships with one another.

Setting Up a Liferay Instance

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080

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.

Next, create three related custom objects:

1. Open the Global Menu (), go to the Control Panel tab, and click 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 name field to each object draft.

   Label	Field Name	Type	Required
   Name	name	Text	✔

4. Add these relationships to the able object:

   Label	Relationship Name	Type	Object
   Able to Baker	ableToBaker	One to Many	Baker
   Able to Charlie	ableToCharlie	One to Many	Charlie

5. Publish each object.

Once published, you can access their REST APIs, including the following relationship APIs:

Preparing the Sample Code

Run these 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-f9m2.zip -O

unzip liferay-f9m2.zip

The sample code includes commands for creating entries for each object and using their relationship APIs.

Using the Sample Code

Use the REST APIs to add object entries and manage their relationships:

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

   cd liferay-f9m2/curl
   

2. Run POST commands to create three entries for each object. These entries have predefined external reference codes (ERCs) following the [objectname]-[number] naming pattern (e.g., able-one).

   ./Able_POST_Batch.sh
   

   ./Baker_POST_Batch.sh
   

   ./Charlie_POST_Batch.sh
   

3. Run Able_PUT_AbleToBaker_ByExternalReferenceCode with the able-one ERC and all three baker ERCs.

   ./Able_PUT_AbleToBaker_ByExternalReferenceCode.sh able-one baker-one baker-two baker-three
   

   This relates the able entry with the baker entries and prints the response.

   {
     ...
     "externalReferenceCode" : "baker-one",
     "id" : 42427,
     ...
     "name" : "Baker 1",
     "r_ableToBaker_c_ableId" : 42421,
     "r_ableToBaker_c_ableERC" : "able-one"
   }
   
   {
     ...
     "externalReferenceCode" : "baker-two",
     "id" : 42429,
     ...
     "name" : "Baker 2",
     "r_ableToBaker_c_ableId" : 42421,
     "r_ableToBaker_c_ableERC" : "able-one"
   }
   
   {
     ...
     "externalReferenceCode" : "baker-three",
     "id" : 42431,
     ...
     "name" : "Baker 3",
     "r_ableToBaker_c_ableId" : 42421,
     "r_ableToBaker_c_ableERC" : "able-one"
   }
   

4. Run Able_DELETE_AbleToBaker_ById with two IDs: the ID for able-one and the ID for baker-three.

   ./Able_DELETE_AbleToBaker_ById.sh {able-entry-id} {baker-entry-id}
   

   This disassociates the entries.

5. Run Able_GET_AbleToBaker_ById with the same able ID to confirm they are no longer related.

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

   {
     ...
     "externalReferenceCode" : "baker-two",
     "id" : 42429,
     ...
     "name" : "Baker 2",
     "r_ableToBaker_c_ableId" : 42421,
     "r_ableToBaker_c_ableERC" : "able-one"
   },
   {
     ...
     "externalReferenceCode" : "baker-one",
     "id" : 42427,
     ...
     "name" : "Baker 1",
     "r_ableToBaker_c_ableId" : 42421,
     "r_ableToBaker_c_ableERC" : "able-one"
   }
   

6. Run Able_PUT_AbleToCharlie_ByExternalReferenceCode with the able-one ERC and all three charlie ERCs.

   ./Able_PUT_AbleToCharlie_ByExternalReferenceCode.sh able-one charlie-one charlie-two charlie-three
   

   This relates the able entry with the charlie entries and prints the response.

   {
     ...
     "externalReferenceCode" : "charlie-one",
     "id" : 42433,
     ...
     "name" : "Charlie 1"
   }
   {
     ...
     "externalReferenceCode" : "charlie-two",
     "id" : 42435,
     ...
     "name" : "Charlie 2"
   }
   {
     ...
     "externalReferenceCode" : "charlie-three",
     "id" : 42437,
     ...
     "name" : "Charlie 3"
   }
   

7. Run Charlie_GET_AbleToCharlie_ById with the ID for charlie-one.

   ./Charlie_GET_AbleToCharlie_ById.sh {charlie-entry-id}
   

   This returns a list of all able entries related to the specified charlie entry.

   {
     ...
     "items" : [ {
       ...
       "externalReferenceCode" : "able-one",
       "id" : 42421,
       ...
       "name" : "Able 1"
     } ],
     "lastPage" : 1,
     "page" : 1,
     "pageSize" : 1,
     "totalCount" : 1
   }
   

8. Run Charlie_PUT_AbleToCharlie_ByExternalReferenceCode with the charlie-one and able-two ERCs.

   ./Charlie_PUT_AbleToCharlie_ByExternalReferenceCode.sh charlie-one able-two
   

   This relates the charlie entry to another able entry.

   {
     ...
     "externalReferenceCode" : "able-two",
     "id" : 42423,
     ...
     "name" : "Able 2"
   }
   

9. Run Charlie_GET_AbleToCharlie_ById with the ID for charlie-one and confirm there are now two related able entries.

   ./Charlie_GET_AbleToCharlie_ById.sh {charlie-entry-id}
   

   {
     ...
     "items" : [ {
       ...
       "externalReferenceCode" : "able-two",
       "id" : 42423,
       ...
       "name" : "Able 2"
     }, {
       ...
       "externalReferenceCode" : "able-one",
       "id" : 42421,
       ...
       "name" : "Able 1"
     } ],
     "lastPage" : 1,
     "page" : 1,
     "pageSize" : 2,
     "totalCount" : 2
   }
   

10. Run Able_GET_ById with the ID for able-one.

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

    This command uses the nestedFields parameter to return all related baker and charlie entries.

    {
      "externalReferenceCode" : "able-one",
      "id" : 42421,
      ...
      "ableToCharlie" : [ {
        ...
        "externalReferenceCode" : "charlie-one",
        "id" : 42433,
        ...
        "name" : "Charlie 1"
      }, {
        ...
        "externalReferenceCode" : "charlie-two",
        "id" : 42435,
        ...
        "name" : "Charlie 2"
      }, {
        ...
        "externalReferenceCode" : "charlie-three",
        "id" : 42437,
        ...
        "name" : "Charlie 3"
      } ],
      "name" : "Able 1",
      "ableToBaker" : [ {
        ...
        "externalReferenceCode" : "baker-one",
        "id" : 42427,
        ...
        "name" : "Baker 1",
        "r_ableToBaker_c_ableId" : 42421,
        "r_ableToBaker_c_ableERC" : "able-one"
      }, {
        ...
        "externalReferenceCode" : "baker-two",
        "id" : 42429,
        ...
        "name" : "Baker 2",
        "r_ableToBaker_c_ableId" : 42421,
        "r_ableToBaker_c_ableERC" : "able-one"
      } ]
    }
    

    See Using nestedFields to Query Related Entries for more information on the nestedFields parameter.

Examining the Code

Charlie_PUT_AbleToCharlie_ByExternalReferenceCode

curl \
	"http://localhost:8080/o/c/charlies/by-external-reference-code/${1}/ableToCharlie/${2}" \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "test@liferay.com:learn"

Charlie_GET_AbleToCharlie_ById

curl \
	"http://localhost:8080/o/c/charlies/${1}/ableToCharlie" \
	--header "Content-Type: application/json" \
	--user "test@liferay.com:learn"

Able_DELETE_AbleToBaker_ById

curl \
	"http://localhost:8080/o/c/ables/${1}/ableToBaker/${2}" \
	--header "Content-Type: application/json" \
	--request "DELETE" \
	--user "test@liferay.com:learn"

Able_GET_ById.sh

curl \
	"http://localhost:8080/o/c/ables/${1}/?nestedFields=ableToBaker,ableToCharlie" \
	--user "test@liferay.com:learn"

Related Topics

• Headless Framework Integration
• Using Nested Fields with REST APIs
• Defining Object Relationships