Headless APIs & Decoupled Liferay platform 

We, as software developers, usually need to reach our users through different channels: from web sites to applications running on smart devices (smartphones, smartwatches, ...) or even through IoT devices… and all those solutions, oriented to the different ways that nowadays the users can interact with our systems, share the same content and features.

Even if we are just creating a frontend application that only considers one channel, or one that is responsive to adapt to different channels, we will probably address a lot of common requirements to show the contents to the user: security checks, selection and filter of data that can be presented to a particular user, workflows and notifications, search capabilities, etc…

New times, new needs: Headless and Decoupled Liferay Platform

The same way you won’t probably be implementing by yourself in the UI features that are already available by using some library or toolkit, you won’t want to implement from scratch all those features if you already have a backend platform -like Liferay Portal- that offers a rich and well proven set of those features out of the box  (and extension points to implement or customize any additional feature that you may have).

The concept of Headless CMS has gained a lot of popularity recently by allowing front-end developers to access content management capabilities and core services while using the tools they are most comfortable with and the front-end technologies they prefer.

A pure Headless CMS option is optimal when there is a need for a custom frontend and there is a strong front-end development team. Some cases when it might not be an optimal solution are:

  1. When the company doesn't have a strong front-end development team.
  2. The value added of a custom frontend is lower than the investment necessary to build it.
  3. When it's desired to provide more control to business users and content authors over the end result, allowing them to preview it before publishing.

In all of these cases, a good option to consider is a Decoupled CMS, which offers the option to mix a headless approach along with a full UI, allowing companies to choose for each project and need what's the best fit.

In Liferay, we have put a lot of effort and care in making Liferay Portal a Decoupled Platform, giving our users the choice of when to use a headless approach and when not to without making it a one-time decision being able to change from one to the other at any time.

Headless APIs & Decoupled support in Liferay 7.2 (and also the latest 7.1!)

As part of this goal to add to Liferay that Decoupled and Headless nature, we have invested a lot of time in designing a good set of APIs on top of some of the services that are already offered by Liferay Portal.

To choose and prioritize the design of these new REST APIs we have kept business use cases and needs in mind. They are not just simple CRUD representation of Liferay’s entities, but empower developers with the functionality that covers the requirements driven by two main use cases:

  • Development of SPAs and other custom frontends
  • Extending the same user experience that you already have on the web to multiple devices, adapting to the specific nature of each channel

Sample use diagram of Headless APIs for Custom Frontends: Users create content using the Management UI and the SPA frontend Apps consume those contents through the Liferay DXP's Headless Content Delivery APIs

As a result of our work on these use cases, most APIs fall in the category of Delivery APIs. In particular, a lot of effort has been put into strong filtering, searching and sorting capabilities, which are the most common needs for these two use cases, especially for Web Content and Documents.

These APIs have also been back-ported to the latest Liferay 7.1 (FixPack 12), so that if you are already using this version, you can benefit from Liferay in scenarios where you prefer a custom front-end application to access Liferay services.

The foundations of the REST APIs design: Open API and REST Builder

We have put a lot of thoughts and discussions during our process of designing not only the APIs but also the process to build these APIs (and the ones that will come).

To design an API, the main focus must be put in the design of the model and the contract that it’s going to be exposed to the client, keeping in mind the use cases that the customer needs to cover.

Steps in an "API Design first" approach: First, define the use cases; then, write the API Specification; next, generate the code stubs; and finally, implement the business logic

To write the API specification, we have chosen to start with OpenAPI as this is the most widely adopted API modelling and documentation standard. It is supported by multiple tools that our customers may already be using which will facilitate creating consumers of the API. All of our APIs are publicly available at where they can be played around as well.

In addition to our APIs, we are also providing our customers and community with a tool called REST Builder, that facilitates creating REST APIs from an Open API definition. It’s important to note though that using REST Builder is optional, so you can also choose to use JAX-RS directly or other OpenAPI generators.

How can the Headless APIs help me?

As we already said in the beginning, think about all the new ways that you could create to communicate with your users and reach them no matter the channel they prefer to use to consume your content and business services.

You could use Headless APIs to consume content published using Liferay Portal’s mechanisms (security, publication workflows, versioning, etc…)  from other applications, integrating other backend or frontend systems that depends on such information. Or you could create your custom frontend application, using React, Vue, Angular or any other technology stack you use for your apps, while still keeping the benefits of all the features that Liferay Portal provides.

There are also other useful scenarios, like creating custom bots that interact with your users on a chat channel, providing information stored in liferay backend. Or any other specific application addressed to a particular channel: an app for the smartphone or the smartwatch, etc…


We have put a lot of effort to improve our APIs and adapt to new scenarios in which Liferay Portal shines and that can be extended by all the different channels the user can use to consume your services. You will probably find a lot of new ideas if you think in all those channels

If you need to go one step further in creating a new experience for your users while still getting the benefits of all the features that Liferay offers you, you may want to explore the new Headless APIs to extend your services providing an omnichannel experience.

You are not limited by the Web! Think out of the browser and explore all those new possibilities that the Headless APIs open.

Just download Liferay Portal 7.2 GA 1 and check the Headless APIs docs to help you get started.


It would be fantastic if there were some clear examples on the way of using REST Builder tool. For now it's quite cryptic.