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.
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. |
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.
Capabilities
Product
Education
Contact Us