Consuming REST Services
Liferay DXP contains REST services for most of its applications. These services are fully OpenAPI compliant. Here, you’ll learn how to consume them. This takes only three steps:
- Identify the service you wish to consume.
- Identify the site containing the data you need.
- Make the service call using credentials that have access to the data.
This example uses Docker image with a fresh install of Liferay DXP.
Identify the Service to Consume
You need a running Liferay DXP to call its REST services.
Start a new Liferay instance by running
docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.75-ga75
Sign in to Liferay at http://localhost:8080. Use the email address [email protected] and the password test. When prompted, change the password to learn.
Liferay DXP’s REST services are published at this URL:
http[s]://[hostname]:[port]/o/api
On your Docker instance, you can find them here:
http://localhost:8080/o/api
APIs are divided into several categories. This example uses the BlogPosting
service to retrieve blog posts from the Blogs widget, but you can use this procedure with any of the published services.
Select the Headless Delivery category. This category contains the
BlogPosting
service. You can use the filter to search for services.Click the Show Schemas button, and on the right side of the screen a list of all the schemas in this category appears.
Keep a browser tab open to the schema browser; when you want to PUT a
BlogPosting
, you’ll need its schema.
Identify the Site Containing the Data
Now you must find the default Site ID:
Open the Site menu (
) and go to Configuration → Site Settings.
Under the Platform section, click Site Configuration. For Liferay DXP versions 7.3 and earlier, click the General tab.
Find the Site identifier under Site ID.
Make the Service Call Using Credentials with Access to the Data
Now you have everything you need to make the call. All web services must be accessed using credentials that have access to the data you’re requesting. The simplest way is to use Basic Auth, which passes credential data in the URL. Since this is insecure, you should only use this method during development. For production, your application should authorize users via OAuth2.
The examples below use cURL.
Calling a Service Using Basic Auth (During Development Only)
To call a service using Basic Auth, provide the credentials in the URL:
curl "http://localhost:8080/o/headless-delivery/v1.0/sites/20122/blog-postings/" -u '[email protected]:learn'
Calling a Service Using OAuth2
For production, create an OAuth2 application and use the OAuth2 process to get an authorization token. Once you have the token, provide it in the HTTP header:
curl -H "Authorization: Bearer d5571ff781dc555415c478872f0755c773fa159" http://localhost:8080/o/headless-delivery/v1.0/sites/20122/blog-postings
Getting and Posting Data
If you run the query above to get all blog postings, you’ll see there aren’t any:
{
"actions" : {
"subscribe" : {
"method" : "PUT",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/{siteId}/blog-postings/subscribe"
},
"unsubscribe" : {
"method" : "PUT",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/{siteId}/blog-postings/unsubscribe"
},
"create" : {
"method" : "POST",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/{siteId}/blog-postings"
}
},
"items" : [ ],
"lastPage" : 1,
"page" : 1,
"pageSize" : 20,
"totalCount" : 0
}
First, you’ll post a blog entry.
Posting a Blog Entry
You can use the schema browser to learn how to post a blog entry.
Go back to your browser tab containing the schema browser. On the right side, click the
BlogPosting
entry to display its schema (see above). This shows the whole data structure for aBlogPosting
, but there are only two required fields:articleBody
headline
Construct a simple JSON document to post a blog entry:
{ "headline": "Test Blog Entry from REST Services", "articleBody": "This article was posted via REST services provided by Liferay DXP." }
Make the request:
curl --header "Content-Type: application/json" --request POST --data '{ "headline": "Test Blog Entry from REST Services", "articleBody": "This article was posted via REST services provided by Liferay DXP." }' http://localhost:8080/o/headless-delivery/v1.0/sites/20122/blog-postings -u [email protected]:learn
Liferay DXP returns the full JSON representation of your blog entry:
{
"actions" : {
"get" : {
"method" : "GET",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
},
"replace" : {
"method" : "PUT",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
},
"update" : {
"method" : "PATCH",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
},
"delete" : {
"method" : "DELETE",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
}
},
"alternativeHeadline" : "",
"articleBody" : "This article was posted via REST services provided by Liferay DXP.",
"creator" : {
"additionalName" : "",
"contentType" : "UserAccount",
"familyName" : "Test",
"givenName" : "Test",
"id" : 20125,
"name" : "Test Test",
"profileURL" : "/web/test"
},
"customFields" : [ ],
"dateCreated" : "2020-03-06T18:02:26Z",
"dateModified" : "2020-03-06T18:02:27Z",
"datePublished" : "2020-03-06T18:02:00Z",
"description" : "",
"encodingFormat" : "text/html",
"friendlyUrlPath" : "test-blog-entry-from-rest-services",
"headline" : "Test Blog Entry from REST Services",
"id" : 35215,
"keywords" : [ ],
"numberOfComments" : 0,
"relatedContents" : [ ],
"siteId" : 20122,
"taxonomyCategories" : [ ]
}
Getting All Blog Entries
Now you can repeat the first query you did to see that the blog entry you posted is there:
curl "http://localhost:8080/o/headless-delivery/v1.0/sites/20122/blog-postings/" -u '[email protected]:learn'
This returns a list of blog entries. The entry you added is the only one in the list:
{
"actions" : {
"subscribe" : {
"method" : "PUT",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/{siteId}/blog-postings/subscribe"
},
"unsubscribe" : {
"method" : "PUT",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/{siteId}/blog-postings/unsubscribe"
},
"create" : {
"method" : "POST",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/sites/{siteId}/blog-postings"
}
},
"items" : [ {
"actions" : {
"get" : {
"method" : "GET",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
},
"replace" : {
"method" : "PUT",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
},
"update" : {
"method" : "PATCH",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
},
"delete" : {
"method" : "DELETE",
"href" : "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/{blogPostingId}"
}
},
"alternativeHeadline" : "",
"articleBody" : "This article was posted via REST services provided by Liferay DXP.",
"creator" : {
"additionalName" : "",
"contentType" : "UserAccount",
"familyName" : "Test",
"givenName" : "Test",
"id" : 20125,
"name" : "Test Test",
"profileURL" : "/web/test"
},
"customFields" : [ ],
"dateCreated" : "2020-03-06T18:02:26Z",
"dateModified" : "2020-03-06T18:02:27Z",
"datePublished" : "2020-03-06T18:02:00Z",
"description" : "",
"encodingFormat" : "text/html",
"friendlyUrlPath" : "test-blog-entry-from-rest-services",
"headline" : "Test Blog Entry from REST Services",
"id" : 35215,
"keywords" : [ ],
"numberOfComments" : 0,
"relatedContents" : [ ],
"siteId" : 20122,
"taxonomyCategories" : [ ]
} ],
"lastPage" : 1,
"page" : 1,
"pageSize" : 20,
"totalCount" : 1
}
Getting a Single Blog Entry
Each time you’ve made a request, Liferay DXP has returned other possible endpoints. One of these is to get a single blog entry by its ID. If you know your entry’s ID, you can retrieve it:
curl "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/35215" -u [email protected]:learn
This returns the same blog entry.
Deleting a Blog Entry
If you know its ID, you can also delete your blog entry:
curl -X DELETE "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/35215" -u [email protected]:learn
In this case, nothing is returned, but you can verify your entry is gone by requesting it as you did above:
curl "http://localhost:8080/o/headless-delivery/v1.0/blog-postings/35215" -u [email protected]:learn
Liferay DXP then returns this JSON document in response:
{
"status" : "NOT_FOUND",
"title" : "No BlogsEntry exists with the primary key 35215"
}
Congratulations! You’ve now learned how to call Liferay DXP’s REST services. Remember that the examples above use Basic Auth: for production, use OAuth2 to call services in a secure way.