Using Liferay as a Headless Platform
Liferay provides a suite of APIs that perform the same kinds of actions available in the web interface. This is essential when you must get data in a machine-readable format, for example in writing mobile applications, custom web applications, or automated processes. While taking more effort than the out-of-the-box interface, it comes with even more power to get things done.
Ways to Connect
There are three different approaches available for clients to connect to Liferay DXP via web API:
- Headless REST APIs, conforming to the OpenAPI specification
- The GraphQL API conforming to the GraphQL specification
- Plain Web/REST Services, generated by Service Builder
Headless REST APIs
Liferay’s headless APIs allow RESTful interaction with Liferay DXP resources. These APIs follow the OpenAPI specification, which defines a standard for REST interfaces, allowing for more straightforward implementation and consumption.
To view detailed information on these APIs, use your browser and access Liferay’s API Explorer at [server]:[port]/o/api (e.g. http://localhost:8080/o/api). Or in the command line, access the complete list with cURL. For example:
curl \
"http://localhost:8080/o/api" \
-u "test@liferay.com:learn"
The most relevant documentation is also available at [server]:[port]/o/[api-name]/[api-version]/openapi.[yaml or json] in a raw format. Documentation is also available on SwaggerHub, but may not match if you are running a previous version.
To view the OpenAPI specifications for all the APIs, use your browser and access [server]:[port]/o/api?endpoint=[server]:[port]/o/openapi/openapi.json. (e.g. http://localhost:8080/o/api?endpoint=http://localhost:8080/o/openapi/openapi.json). Or download the full list in JSON format or YAML format with cURL. For example:
curl \
"http://localhost:8080/o/openapi/openapi.json" \
-o "openapi.json" \
-u "test@liferay.com:learn"
curl \
"http://localhost:8080/o/openapi/openapi.yaml" \
-o "openapi.yaml" \
-u "test@liferay.com:learn"
Download of this full openapi.[json|yaml] file is available in Liferay DXP 7.4 U69/Liferay Portal 7.4 GA69 and above.
GraphQL API
The GraphQL API is a query language that supports interactions similar to the headless REST APIs, but with slightly more flexibility. Liferay DXP exposes this API at [server][:port]/o/graphql.
You can find detailed information by exploring the API or its documentation through a GraphQL client. Liferay includes a built-in client that can be found on a running instance at [server][:port]/o/api (select GraphQL on the top-right).
Plain Web/REST Services
Liferay’s Web Services are part of an older framework, still supported by DXP but no longer recommended for complex headless operations. These APIs are closely tied to Liferay DXP’s internal workings and thus lack the power and flexibility that the newer headless options provide.
However, Web Services may provide a simpler way to execute certain tasks. See Service Builder Web Services for how to use them.
Features
Work with Any Client
Liferay’s headless APIs serve data over the web, so any application capable of making web calls can serve as a client. These APIs respond with JSON content by default, but also support XML natively. Extensions can serve content in any other way you might need. See API Headers Reference to learn more.
Connect Securely
Just like with Liferay’s web interface, all interactions via headless API are made using a particular User account (or as a guest). Liferay’s APIs support three ways of authenticating: via basic authentication, via OAuth token, and via cookie. See API Headers Reference for how to make this happen. It’s also possible to make API requests as a guest – see Making Unauthenticated Requests for more details.
Keep Data Size Manageable
Working with large sets of data can quickly become overwhelming for a client to handle; performance issues are frustrating for users, and bandwidth can be expensive. Liferay’s headless APIs provide ways to break down collections into manageable chunks and retrieve the exact data you want.
By passing page and pageSize parameters in a request, you can tell the API how much information you want at a time and which subset of information you want in a given request. The sort parameter is also effective in combination with paged responses, allowing you to indicate which elements should be returned first.
The search parameter executes a keyword search, yielding elements that contain that keyword in any part of their entries. The filter parameter executes a similar search, but specifies exactly where in the entry the content must be contained.
The fields parameter requests only specific fields to be enumerated in each of the elements in the response, and conversely the restrictFields parameter excludes the given fields from being returned.
The flatten parameter executes your request out of a hierarchical context, for hierarchical APIs. This allows you, for instance, to search for any Organization called “Marketing” rather than having to traverse the org-chart to find the relevant Organization.
For specifics on how to use any of these parameters see API Headers Reference.