Consuming REST Services

Documentation Menu
Go Back

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:

  1. Identify the service you wish to consume.
  2. Identify the site containing the data you need.
  3. 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.

  1. Select the Headless Delivery category. This category contains the BlogPosting service. You can use the filter to search for services.

  2. Click the Show Schemas button, and on the right side of the screen a list of all the schemas in this category appears.

  3. Keep a browser tab open to the schema browser; when you want to PUT a BlogPosting, you’ll need its schema.

The schema browser makes it convenient to find and call the service you want.

Identify the Site Containing the Data

Now you must find the default Site ID:

  1. Open the Site menu (Site menu) and go to Configuration → Site Settings.

  2. Under the Platform section, click Site Configuration. For Liferay DXP versions 7.3 and earlier, click the General tab.

  3. Find the Site identifier under Site ID.

    Identify the Site Id under the Site Settings and Site Configuration option.

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.

The schema for any service is published on your Liferay DXP instance.

  1. 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 a BlogPosting, but there are only two required fields:

    • articleBody
    • headline

  2. 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."
}

  3. 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.

Not finding what you're looking for?

Pardon our dust as we revamp and transition our product documentation to this site. If something seems missing, please check Liferay Help Center documentation for Liferay DXP 7.2 and previous versions.

Try Liferay's Help Center