A Headless API example using Gatsby (Part 1)

Creating a basic Gatsby source plugin for Liferay

A few weeks ago, I had a need for a simple static site to host some documentation for internal customers at my work.  What I needed for the site was basically a Home page and a series of documentation pages very similar to what Liferay uses for Clay UI. I thought about using Liferay and the Knowledge Base to achieve this, but for a few reasons I did not have an existing instance that made sense to use.

Looking for a solution

I had remembered that Liferay had a project called "electric.js" and I thought from what I remembered it could be used for such a task. However, the site seemed to not exist anymore. So, after some internet searching it appears the project had been retired in place of using a static site generator called Gatsby. Gatsby is based on React and allows you to create fully styled HTML pages using templates while pulling data from different sources such as markdown files, databases or even a headless CMS …such as Liferay.

This sounded just what I was looking for. I could quickly stand up my site, focusing on the content using markdown files, and later tryout Liferay’s new Headless API to power some of the content.

Gatsby uses what is called source plugins to load data from almost anywhere. There are many different source plugins available already. However, at this time there did not seem to be a plugin for Liferay.

Therefore, in this guide we will create a basic Gatsby source plugin for Liferay to demonstrate the new Headless API. We will use this plugin to pull in some web content articles into our static site.

Setting everything up

Let’s get started first by setting up a local Gatsby site. I will assume you have Node.js, npm, and Git already installed, but if not here are some instructions from the Gatsby site.  Now, let’s install the Gatsby CLI.

npm install -g gatsby-cli

 

Next, create a new Gatsby site. Gatsby has many “starters” that are basically partially built sites or boilerplates that you can use to get going fast. This is what I ended up using in my case. However, for purposes of this post and to keep things simple, we are going to use the basic default starter. 

gatsby new gatsby-liferay-site https://github.com/gatsbyjs/gatsby-starter-default

 

This will create a new site called “gatsby-liferay-site” from the default starter. 

Next, change to the gatsby-liferay-site directory, enter gatsby develop to start a local development server and view the site at http://localhost:8000.

Great, now we have a working Gatsby site. Next, let’s use Liferay 7.2 and create some web content articles to source as data for our new Gatsby site. Download a Liferay 7.2 turnkey bundle if you do not already have one and start it up. 

Create a couple of Basic Web Content articles and use the editor to make some styling changes. 

 

Additionally, add a tag of “news” to each of the articles. Then publish the articles.

Testing the API

Next, we want test Liferay’s headless API and retrieve our articles. Assuming your local Liferay is running at localhost:8080, use curl and query the server. Replace SITE_ID with the real site id or group id of your Liferay site.

curl "http://localhost:8080/o/headless-delivery/v1.0/sites/SITE_ID/structured-contents/" -u 'test@liferay.com:test'

 

This should return a listing of our web content articles that is similar to this.

{

  "items" : [ {

    "availableLanguages" : [ "en-US" ],

    "contentFields" : [ {

      "dataType" : "html",

      "name" : "content",

      "repeatable" : false,

      "value" : {

        "data" : "<h1>Lorem ipsum</h1>\n\n<p>dolor sit amet, consectetur adipiscing elit. Morbi vel pellentesque elit, sit amet pretium ligula. Praesent viverra vehicula rutrum. Vivamus at leo vitae velit euismod porta in ut dui. Donec convallis porttitor eleifend. Sed blandit pretium risus at dignissim. In tortor ante, tristique eu sagittis quis, mollis at ante. Phasellus interdum rhoncus pretium. Proin et fringilla libero. Morbi molestie nisl vitae fermentum rutrum. Donec ullamcorper, sapien non tempor ultricies, dui massa mattis metus, quis cursus lectus turpis vitae quam. Ut a ultrices ex, posuere maximus massa. Phasellus non dui at nibh venenatis tempus.</p>\n\n<h2>&nbsp;</h2>\n\n<h2>Nunc consectetur,</h2>\n\n<p>risus ut ultrices aliquet, mauris dolor consectetur mauris, nec molestie dui lectus semper tellus. Donec molestie iaculis convallis. Nam sollicitudin, libero convallis porta consequat, nisi nunc eleifend est, a tempus felis lorem mollis nisi. Vestibulum metus leo, auctor ac varius nec, pharetra et justo. Integer dapibus quam ultrices, condimentum nunc faucibus, imperdiet massa. Cras convallis eros vel porta volutpat. Aliquam dictum at mi ac facilisis. Vestibulum fringilla bibendum metus ac elementum. Curabitur in nulla purus. Pellentesque sagittis magna nunc, a sodales sem maximus in. Praesent cursus nunc at neque consectetur, eu efficitur dolor malesuada.</p>\n\n<p>&nbsp;</p>"

      }

    } ],

    "contentStructureId" : 34030,

    "creator" : {

      "familyName" : "Test",

      "givenName" : "Test",

      "id" : 20129,

      "name" : "Test Test",

      "profileURL" : "/web/test"

    },

    "dateCreated" : "2019-09-17T15:17:25Z",

    "dateModified" : "2019-09-27T18:38:22Z",

    "datePublished" : "2019-09-17T15:12:00Z",

    "description" : "<p>some quick content for displaying headless</p>",

    "friendlyUrlPath" : "a-simple-article",

    "id" : 34310,

    "key" : "34308",

    "keywords" : [ "news" ],

    "numberOfComments" : 0,

    "renderedContents" : [ {

      "renderedContentURL" : "http://localhost:8080/o/headless-delivery/v1.0/structured-contents/34310/rendered-content/34033",

      "templateName" : "Basic Web Content"

    } ],

    "siteId" : 20123,

    "title" : "A simple article",

    "uuid" : "83f44391-39aa-bcc9-601d-a99d0864456b"

  }…

 

The  API also allows you to search, filter and restrict fields. Check out the documentation to learn more. We will look at filtering articles by the “news” tag in the next part. You can also explore the available APIs at SwaggerHub. To learn more about creating and consuming your own custom headless APIs see David Nebinger’s recent blog series on Creating Headless APIs.

In next part we will create the Gatsby source plugin to pull in our content articles from Liferay.

Blogs