Liferay REST APIs Beta release

I’m happy to announce the release of the first beta for the new set of Liferay REST APIs. But before going into details, for those of you who might not be aware of this project, I’d like to give you some context.

Our vision

Over the last year and a half, we have been working on a new set of REST APIs for Liferay following industries best practices. The goal of these APIs is to allow developers to access and manage all the content stored in Liferay in an easy way, so you can focus on building great experiences and not having to struggle with how to get that content.

Our long-term goal is to satisfy the needs of the different Liferay users, covering all the important use cases by offering the needed features by each one of them. Before fulfilling the whole vision and with the feedback received from several customers that we interviewed, we decided to focus first on helping you deliver content to your end users.

What will you find on this beta

Now that we are all on the same page, let’s talk about what will you find in this first version of the APIs. The scenario that we had in mind while building them was to allow developers to build their own frontend to expose the content created and stored in Liferay. With that objective we prioritized the features to implement in order to support, among others, the following use cases:

  • Access published structured content. By doing so, you’ll be able to create for example an SPA to show the latest news from your company.
    • To help you find the right content, we’ve implemented several filtering and sorting options, such as: filter and sort by title, publishing date, tags, etc.
  • Access the documents and media repositories. Enrich your experiences by having at your disposal the whole media library that you are already benefiting from.
  • Access the blog entries that are already published. Access the content and expose it with the best appearance your developers can think of.

Apart from these three main use cases, we are making possible to access and perform actions for other types of information. To check the whole set of resources and actions available in this beta, see the first draft of the documentation and the Open API profile here: https://headlessapis.wedeploy.io/

 

How can I get access to the beta

We hope that by this time you are eager to give it a try to these APIs, test them, check if they could fit in your projects and give us feedback to make them greater. To make it more convenient for you, we have prepared a docker image containing the latest Liferay DXP 7.1 version with the first beta installed. In doing so, we provide you with a full sandbox to play with, not affecting your current environments.

In order to get the docker image and run the beta, follow the installation instructions:

  • Pre requirements: install Docker to run the beta image
  • Create the config file com.liferay.apio.architect.internal.application.ApioApplication-default.config. Add the following properties to the file:
oauth2.scopechecker.type="none" 
auth.verifier.auth.verifier.BasicAuthHeaderAuthVerifier.urls.includes="*"
auth.verifier.auth.verifier.OAuth2RestAuthVerifier.urls.includes="*"
auth.verifier.guest.allowed="true"

Note that the last property (auth.verifier.guest.allowed) lets guests access public content via the APIs. To turn this off, set the property to false.

Store this file under “/Users/liferay/Downloads/xyz123/files/osgi/configs” being “/Users/liferay/Downloads/” the folder where the docker image will be downloaded.

  • Execute the following command: "docker run -it -p 8080:8080 -v /Users/liferay/Downloads/xyz123:/etc/liferay/mount liferay/portal-snapshot:7.1.x-201812071242-af6321a" 
    • Substitute “/Users/liferay/Downloads/” with the folder where the docker image will be downloaded.
    • Note:  this command will download the docker image for you if it does not find it in your computer.

We know that some of you would like to test the APIs in your own environments so additionally, we will release the APIs as a marketplace app during January. We’ll make a separate announcement once the app is available.

Be aware that this is a beta product so we strongly recommend to not use them for production projects and we expect several breaking changes before the final version is released in order to take into account your feedback.

How to give feedback

Once you had given them a chance (or while testing them) we would like you to tell us about the experience using them: have you found any error? do you miss a feature that you think is crucial? Just access the Liferay portal Jira project here (https://issues.liferay.com/projects/LPS/summary) and create an issue setting the component to “HeadlessCMS” (the most common issue types will be bug or feature request). We’ll give you an answer as soon as possible.

  •  
Blogs

Hi Pablo,  thanks for sharing! Can you tell me where can I found the docker images or when the'll be available? One more question, are you planning to include content targeting API as well?

Hi Denis,

 

the docker image is already available and you don't need to download the image separately, the docker command that I put in the instructions will download the image. I'll add a comment to the post so it is clearer.

 

About the content targeting API, I do not think it will be ready for 7.2, but we do think on including it at some point in time.

Those of you not very familiar with Docker may be surprised that everything added (content, users, ... ) will disappear if the container is stopped or crashes. To prevent that you can extract the `data` folder from it, save it locally and mount it as volume when you start the container. Here is how to do it

 

1. start the container with `docker run -it -p 8080:8080  liferay/portal-snapshot:7.1.x-201812071242-af6321a` 

 

2. check the container id by running `docker ps` 

 

3. copy the `data` folder  by running `docker cp <CONTAINERID>:/opt/liferay/data /PATH/TO/YOUR/data`

 

4. stop the container

 

 

From that point on you can run the container with `docker run -it -p 8080:8080 -v /PATH/TO/YOUR/mount:/etc/liferay/mount -v /PATH/TO/YOUR/data:/opt/liferay/data  liferay/portal-snapshot:7.1.x-201812071242-af6321a` and the data will be safely stored on your local file system.

Hey Pablo, when will this be published to marketplace? I am really eager to test on our 7.1 instance :)

Hi Pablo,

Liferay has a great categorization system for the assets/contents it can manage. I'd like to know whether the Headless API allows to filter on specific categories and if the categorization information is present as attribute for entities. I was taking a look at the documentation https://headlessapis.wedeploy.io/docs/general/filtering.html but it seems is not possible. Can you help me understanding if this capability is available of you think will be supported in the future?

 

Thanks,

Denis