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

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.

You can find detailed information on these APIs by accessing the definitions on a running Liferay DXP instance at [server][:port]/o/api. The most relevant documentation is also available at [server][:port]/o/[api-name]/[api-version]/openapi.[yaml or json] in a raw format. The documentation is available on SwaggerHub, but may not match your running version.


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.


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 Parameters Reference.