Mastering Data Modeling with Liferay Objects

Course Overview

Accessing Object via Headless APIs

Liferay's low-code tools also simplify how you interact with your data models. When you publish a custom object, Liferay automatically generates REST APIs for managing the object and its data. The generated APIs vary based on the object's scope (company or site). Also, if the definition includes relationships or standalone actions, Liferay generates endpoints for interacting with them.

Liferay's low-code tools also simplify how you interact with your data models.

All generated APIs follow a common naming pattern: /c/[pluralObjectLabel]. For an active Liferay object, you can perform CRUD operations, run complex queries, trigger actions, manage permissions, relate entries, and more using these APIs.

Company-Scoped REST APIs

These APIs are available for company-scoped objects:

HTTP Method HTTP Endpoint Description
DELETE /by-external-reference-code/{erc} Deletes the specified entry.
GET /by-external-reference-code/{erc} Returns details for the specified entry.
PATCH /by-external-reference-code/{erc} Updates the specified entry; only fields included in the API call are changed.
PUT /by-external-reference-code/{erc} Replaces the specified entry’s details with those provided in the API call.
GET / Returns a complete list of entries in a Liferay instance; you can paginate, filter, search, and sort results.
POST / Creates a new entry using the details provided in the API call.
DELETE /batch Deletes multiple entries.
POST /batch Creates multiple entries using the details provided in the API call.
PUT /batch Replaces multiple entries using the details provided in the API call.
DELETE /{entryId} Deletes the specified entry.
GET /{entryId} Returns details for the specified entry.
PATCH /{entryId} Updates the specified entry; only fields included in the API call are changed.
PUT /{entryId} Replaces the specified entry’s details with those provided in the API call.
GET /{entryId}permissions Returns permission details for the specified entry.
PUT /{entryId}permissions Replaces the specified entry’s permission details with those provided in the API call.
POST /export-batch Returns multiple entries using the parameters provided in the API call.

 

Choosing Between POST, PUT, and PATCH Methods

When choosing between POST, PUT and PATCH methods, consider the source of truth for the object's data and whether Liferay enriches that data. POST creates new objects, PUT replaces the entire object, while PATCH updates only the provided fields.

  • Liferay as Source: If Liferay is the primary source of data for the object, use PUT to replace the entire object with the data provided in the API call. Use PATCH to update only specific fields, preserving any existing data that is not included in the request.

  • External System as Source: If an external system is the source of truth, and Liferay does not enrich the data, use PUT to replace the object with the data received from the external system. This ensures that Liferay's copy of the object remains synchronized with the external source.

  • External System as Source with Liferay Enrichment: If an external system is the source of truth, but Liferay enriches the data with additional fields or information, use PATCH to update only the fields received from the external system. This preserves Liferay's enrichment while keeping the core data synchronized with the external source.

Site-Scoped REST APIs

These APIs are available for site-scoped objects. Use the appropriate identifier (e.g., site ID) for scopeKey:

HTTP Method HTTP Endpoint Description
DELETE /scopes/{scopeKey}/by-external-reference-code/{erc} Deletes the specified entry.
GET /scopes/{scopeKey}/by-external-reference-code/{erc} Returns details for the specified entry.
PATCH /scopes/{scopeKey}/by-external-reference-code/{erc} Updates the specified entry; only fields included in the API call are changed.
PUT /scopes/{scopeKey}/by-external-reference-code/{erc} Replaces the specified entry’s details with those provided in the API call.
GET /scopes/{scopeKey} Returns a complete list of entries in the specified scope; you can paginate, filter, search, and sort results.
POST /scopes/{scopeKey} Creates a new entry in the specified scope using the details provided in the API call.
DELETE /{entryId} Deletes the specified entry.
GET /{entryId} Returns details for the specified entry.
PATCH /{entryId} Updates the specified entry; only fields included in the API call are changed.
PUT /{entryId} Replaces the specified entry’s details with those provided in the API call.
GET /{entryId}permissions Returns permission details for the specified entry.
PUT /{entryId}permissions Replaces the specified entry’s permission details with those provided in the API call.

 

For batch import/export of site-scoped objects, use the headless-admin-batch API, specifically the importTask and exportTask endpoints.

Relationship REST APIs

When you define one-to-many and many-to-many relationships between objects, Liferay generates endpoints for querying and managing entry relationships. This includes a GET endpoint for returning related object entries, PUT endpoints for relating entries, and a DELETE endpoint for disassociating related entries.

HTTP Method HTTP Endpoint Description
GET /{entryId}/relationshipName Returns all entries related to the specified entry through the relationship.
PUT /{entryId}/relationshipName/{relatedEntryId} Uses the relationship to relate the specified object entries.
PUT /by-external-reference-code/{erc}/relationshipName/{relatedERC} Uses the relationship to relate the specified object entries.
DELETE /{entryId}/relationshipName/{relatedEntryId} Disassociates the specified object entries.

 

For site-scoped objects, the ERC endpoint includes the /scope/{scopeKey} prefix. Also, ERC endpoints are not available for system objects.

In addition to these APIs, you can use the nestedFields query parameter with other GET APIs to return an entry with its related entries. When using this parameter, you must provide the name of the relationship you want to include in the output (e.g., nestedFields=ticketAssignee).

Standalone Action REST APIs

Liferay generates these endpoints for triggering standalone actions:

HTTP Method HTTP Endpoint Description
PUT /by-external-reference-code/{erc}/object-actions/actionName Trigger the action using the entry's ERC.
PUT /{entryId}/object-actions/actionName Trigger the action using the entry's ID.

 

For site-scoped objects, the ERC endpoint includes the /scope/{scopeKey} prefix.

GraphQL APIs

Liferay also provides GraphQL APIs to query and mutate object data. All APIs for custom objects are listed under c in Liferay's GraphQL schema. You can use Liferay's integrated GraphiQL IDE to explore schemas, draft queries, and run requests. To access it, go to Liferay’s API Explorer at [server]:[port]/o/api (e.g., localhost:8080/o/api) and click GraphQL.

Conclusion

Liferay provides comprehensive APIs for interacting with your object definitions, empowering you to build integrations, automate processes, and create custom applications. By understanding the different API options and their capabilities, you can seamlessly connect your Liferay objects with other systems and services, extending their functionality and maximizing their value within your digital ecosystem. Next, you’ll use these APIs to import Clarity’s legacy data into their ticketing app.

  • Company-Scoped REST APIs

  • Site-Scoped REST APIs

  • Relationship REST APIs

  • Standalone Action REST APIs

  • GraphQL APIs

  • Conclusion

Loading Knowledge

Capabilities

Product

Education

Contact Us

Connect

Powered by Liferay
© 2024 Liferay Inc. All Rights Reserved • Privacy Policy