holding a fencing mask
PHOTO: Alev Takil

According to a Kentico report entitled “State of Headless CMS Market 2018” (free to download) it is widely expected that the adoption of headless CMS will double by mid-2019. The API-driven environment of a headless CMS provides a multitude of advantages, in particular, from a content distribution and integration perspective.

With the assistance of leading industry practitioners in the headless CMS space, we take a closer look at how a headless CMS works and dive deeper into the inner workings of the APIs used in the platform.

How Is a Headless CMS Different to a Traditional CMS?

A traditional CMS platform like, WordPress or Drupal, come with a front-end presentation layer (the head) that is tightly coupled to the back end, which stores all the content, files, databases and folders out-of-the-box. This presentation layer typically dictates how the content should be delivered and it is normally restricted to web-based applications.

A headless CMS, on the other hand, completely removes the “head” and leaves only the back end, which acts as a central repository for all the content. With a headless CMS, the content stored in the repository can be distributed and delivered to any device, channel or touchpoint via RESTful APIs, making it the ideal solution for brands who want to deliver experiences to their consumers to various touchpoints and Internet of Things (IoT) devices.

Related Article: 24 Headless CMS That Should Be On Your Radar in 2019

What Exactly Is a RESTful API?

A RESTful API is a type of application program interface that utilizes HTTP requests to GET, POST, PUT and DELETE data. Also known as a RESTful web service, it is based on representational state transfer (REST) technology, which is an architectural style and approach to communicating between different services.

Vadim Belski, head of the web development department at ScienceSoft, explained how REST API enables communication via stateless calls. “[With a RESTful API], each message from the client to the server contains all of the needed information and cannot refer to any previous message or data stored on the server side. This makes the server and the client side completely decoupled from each other and provides scalability potential for both.”

Belski added that the REST architecture allows for multiple data formats including JSON, HTML, XML and plain text.

Are There Any Alternatives to REST APIs?

Before REST APIs, there was Simple Object Access Protocol (SOAP) APIs, which allowed systems “written in any language” to communicate with each other. But since REST leverages less bandwidth, REST API became the de factor successor to SOAP.

One potential alternative to REST API is GraphQL, which is a query language for APIs that allows the client to specify what data it needs from the server, which then returns the request back to the client as a JSON. “A great alternative and upcoming API & query language is GraphQL. GraphQL has a number of advantages against REST,” said Stefan Schinkel, chief sales officer at dotCMS. Schinkel listed the advantages:

  • One single endpoint: API/v1/GraphQL.
  • Self-documenting via schema introspection.
  • No over-fetching of data.
  • No need for multiple requests for getting desired data.
  • Client can decide exactly what data they want.

But despite these benefits, Christopher Zimmermann, product manager at Magnolia CMS, highlighted that GraphQL is difficult to optimize and has a lengthy setup procedure. “GraphQL is the cool new kid on the block, but GraphQL is only relevant in some scenarios. Its strong card is allowing front-end developers to request just exactly the content they need, in the format that they want, which can greatly accelerate development cycles,” said Zimmerman. “[GraphQL is] often used to aggregate the information from multiple REST APIs. But GraphQL servers can be time-consuming to set up and difficult to optimize.”

Gabe Aguilo, senior manager of product management at Bloomreach, said that even though GraphQL is still in its early development stages, it does have a number of advantages over REST, but similar to REST, it is limited when it comes to handling large media files. “GraphQL today can be considered to be in an ongoing research and development phase,” said Aguilo. “The key difference, as we see it, is around specific vs. comprehensive data queries. [It] is best for highly intensive data exchange, where you need to receive exactly what you expected, REST can return zero or many results if the queries aren't well structured. However, this doesn't solve, or improve, the situation around large binary objects such as large media files. The same limitations and issues, if not more, exist with Graph vs. REST.”

Related Article: What Is a Headless CMS? Here's Everything You Need To Know

How Do APIs Work Within a Headless CMS?

Aguilio said a REST API in a CMS can be used for various purposes, including:

  • A method to gather and store documents, content and images.
  • To publish content to its ultimate destination, whether that’s to a desktop, mobile or IoT.
  • To manage and administer the CMS platform, including updating content, changing the appearance of a website and back-end administration.

“In the context of a headless CMS, REST APIs basically help to access the content in the repository and return XML or JSON to expose the content to the visitor requesting it. It is one of the most common and modern APIs out there for any business application that makes integration seamless,” said Schinkel.

As far as limitations go, Schinkel explained that REST itself has no limitations. “It's usually the application or environment (SaaS) that dictates restrictions to end-users of the application, for example not to frustrate other users of the SaaS platform from a performance perspective,” he said.

The REST APIs in a headless CMS allow other systems to trigger, write and read content from them. Zimmerman further elaborated on the benefits of using REST APIs. “The beauty of this approach is that software developers of any current or future channel, like a native mobile app, or a React-based javascript front end, or a marketing automation system, or even a smart speaker can read the raw content from the CMS via the REST API and generate the appropriate experience for that channel.”

Are There Any Limitations to a Headless CMS?

Despite the advantages of being able to distribute content to any IoT device and providing the ability to communicate with different services, Zimmerman said the headless approach comes with two downsides for both marketers and content authors.

“First, the editing UI is limited compared to a full CMS, it's typically a form, which doesn't provide the flexibility necessary for crafting convincing landing pages, news articles, or "product universe" experiences. Second, content authors miss the context and instant feedback of a WYSIWYG experience of a page editor. Since a pure headless CMS doesn't render HTML, it can't provide that integrated editing experience.”

To mitigate these drawbacks, and to enable marketers to take advantage of a headless CMS, Zimmerman advised brands to adopt a hybrid headless CMS. “The hybrid headless CMS approach addresses this by keeping the flexible WYSIWYG page editor and providing a REST API which delivers not just the content but also the structure and layout that the content authors created. Front-end developers can use this information to reconstruct these experiences as appropriate in each channel.”

Zimmerman added that there are “exciting developments [to come]” in this space.