Headless and decoupled CMS: the essential guide

What is headless, who is the audience, what are the use cases

This article will tell you everything there is worth knowing on the topic of headless CMSs, also sometimes called decoupled CMSs. You'll learn what headless exactly means, how it is different from the CMSs which you know, why you should care, and who and when should use them. Some etymology and history come as a bonus. Shall we?

Table of contents

Headless CMS in a nutshell

A headless CMS has its front-end component (the head) stripped and removed from its backend, and what remains is a backend delivering content via an API. It thus does not care how and where the content is displayed, and focuses on storing and delivering the content and provides tools to create and organize it – nothing more.

Its counterpart is a standard multi-purpose CMS – coupled CMS – like WordPress or Drupal, which is built in such a way that it is also responsible for giving shape to the content, transforming it into HTML pages and even complete websites.

The most prominent use cases for a headless CMS are:

  • websites and web apps built with MVC-style JavaScript frameworks,
  • mobile apps,
  • static site generator driven websites.

How traditional CMS work

Let's take WordPress as a well-established example. A traditional CMS of this type consists of several components: 0) a database where the content is stored, 1) a web app in which editors work with the content (also known as the admin interface), 2) a web app in which publishers create and design templates which comprise the website, 3) a front-end which takes the content from the database and generates HTML web pages.

Imagine that we remove (2) and (3) from this setup. The head of the CMS – the website itself – is no longer there. You still have a backend which stores and delivers the content and you still have a web app for editors, and that's it. That's the entire CMS.

Such setup is called headless.

The website visitors will not see a Drupal (or any other CMS) theme at the top, and this is where the word headless comes from: the traditional Drupal head is missing.

How headless/decoupled CMS are different

In contrast to WordPress, you would not create a website exclusively with a headless CMS. Typically there are no instruments to do so: a headless CMS has no page templates, no themes, none of all these somewhat aged concepts. Instead, you would build the website separately – with the skills of a talented engineer on your team – while the CMS will be readily pouring content into its pages, serving it from an API.

"How is that better", you might be wondering, "and why should I care?" It's only natural to assume that having no front end is actually worse than a full-fledged CMS of old. It also might be natural to think that working with a single software is better and simpler than with two or several. But bear with us.

The motivation for different CMSs (and for this article) is because there is no single better for any given project. There are different use cases and different circumstances is which going headless makes way more sense. We're exploring them in the next paragraphs.

Audience and use cases

A headless CMS is the best choice for all those who feel limited by the front-end restrictions of a standard CMS. Rich web apps, highly custom layouts and JavaScript MVC frameworks don't quite fit into the architecture of a CMS which closely controls how content looks. To avoid the dirty hacks of undoing a front-end and consequent technical debt, it's best to have a clean setup from the beginning.

It's not only for websites, though. A headless CMS usually delivers content through an API (oftentimes RESTful JSON API), which means that it can deliver content anywhere, on any device. This might immediately ring a bell in the mind of mobile app developers. Yes, headless enables delivering the same content to an iOS app and Android app from one backend – the same backend that would deliver content to the website or any other medium.

So, headless proves hugely beneficial for cross-platform publishing and custom user experiences. It makes publishers, designers and developers happy and, eventually, helps building better products for the public.

If your use case is just a simple old six-page company website, a headless CMS often times is an overkill. Your good old WordPress, Drupal and similar traditional CMSs will perfectly cover that use case and dozens of similar ones.

Headless WordPress: WP plus JSON API plugin

It's possible to install JSON API or JSON REST API plugin on top of WordPress and use it exclusively as a headless CMS. These plugins provides a JSON API to access and modify the content.


  • Simple API to retrieve and manipulate the content
  • Same software, same workflow, editors don't need to learn new tools
  • It's possible to reuse all the existing code and content


  • Built by a third party, so no official support available
  • Possible conflicts with new versions of the WordPress core or other plugins
  • Limited API capabilities

Headless Drupal 7; RESTful module or Drupal 7 + RESTful Web Services module

The RESTful module or the RESTful Web Services module make Drupal headless. The Drupal 8 puts the RESTful Web Services module into its core.


  • Content exposure as JSON or XML, HTTP authentication
  • No need for editors to learn new software or for developers to update the codebase
  • The community is large and is ready to help


  • Drupal forces the users to build websites, which is a problem for those who want to create apps
  • 110 open issues, 52 open bugs
  • Limited API capabilities
  • Possible conflicts with other modules

Contentful, the API-first content management backend


  • Designed for API-first and headless from the start
  • Rich API capabilities for fetching and editing the content
  • Extensive documentation and support from the makers
  • Libraries and frameworks for all major platforms


  • Requires prior content modelling
  • Search-based content management somewhat unusual to users used to tree-based structures
  • Free for only small projects


There is no single right approach and CMS for every use case. However, our intuition and experience suggest that any app-focused project, be it rich web apps or mobile apps, would greatly benefit from using a headless CMS.

Take a look at Contentful, an API-first headless CMS

Further reading

Real needs of real people

Case studies


Discover more Contentful.

If you enjoyed this article, you might like our product as well.

What our product does

Take a look at the API capabilities, delivery infrastructure and friendly editing environment.
See features

What our clients built

From apps and sites to digital signage and iBeacon campaigns — we deliver content everywhere.
See real-life examples