A Developer’s Guide To Headless CMSs

WordPress is behind more than one-third of the internet and represents a paradigm that has dominated web development over the past 20 years.

The tradition is this: Developers spin up a website, lock themselves into a technology stack, and the rest of the company’s content inputs flow through the developers and up to the website. Technical debt festers, and the website, as well as the developers that maintain it, slow down.

Enter the headless CMS. A headless CMS is a simple but compelling proposition: What if we just lopped off the front end of the website and gave you the back end? At first glance, that doesn’t sound like a big deal. At second glance, it’s like cutting the reins between your horse and your carriage and giving you the ability to hook up that carriage to a V-8 engine.

In this article, we’ll offer a third, longer glance, and get deep into the guts of what makes up a headless CMS and what the market for headless CMSs looks like.
What is a headless CMS?A headless CMS is a CMS that is back end only. Rather than storing content and code together, as in traditional CMSs, a headless CMS provides content via an API (usually REST API or GraphQL). It’s a microservices approach to content management.

If the “head” is where your content goes (i.e., the front end, the website), then the “body” is where your content lives (i.e., the back end, where you create and store content).

Headless CMSs are then “headless” because they don’t have a default place, or head, content can go to. Instead, you manage content in a back end and make it available to a separate, distinct front end via an API. Once that content is available via an API, you can have many heads –– a CMS hydra, if you will.

In the old days, a traditional CMS worked because you worried only about rendering content in one place — the website. Now, there are mobile apps, conversational interfaces, mobile sites, VR headsets, wearables, and more, meaning that devs need the ability to disaggregate content from its destination.

There are, essentially, many possible heads for a system that was only ever intended to have one head. If you’re trying to create content for multiple heads in that system, you end up having to create new content for each head, thereby creating a messy web of out-of-date, unsynced silos.

One way to think about the difference is that a traditional CMS manages and delivers content; a headless CMS manages but doesn’t deliver content––but it does make it available for pickup. A traditional CMS sends content right to the user; a headless CMS first sends content to an API.

What a traditional CMS looks like

The difference between the two CMSs becomes clearer the deeper into the weeds you get.

Architecture: A traditional CMS has page-based architecture, meaning it stores elements like texts and graphics as complete pages. The content is the page.

Structure: A traditional CMS is monolithic, meaning that all of its functionalities exist in one system.

Hosting: A traditional CMS is either self-hosted or hosted on a managed server environment.

Workflow: Companies work with a traditional CMS by creating and managing content from within the same system. This tends to lead to waterfall approaches to web development. Devs are dependent on the framework and stack the CMS vendor uses. Content creators “publish” content to the CMS.

Example: In WordPress, content editors use a “What You See Is What You Get” or WYSIWYG editor. PHP links an included theme to a database and pulls pages from the database to the front end. The theme determines content placement and rendering by converting the content into HTML and CSS.

What a Headless CMS Looks Like

Compare the differences in this section and the previous one to better understand the differences between the two kinds of CMSs.

Architecture: A headless CMS has object-based architecture, meaning it stores elements like texts and graphics as separate, distinct objects. These objects exist in a structured but raw format — typically HTML or JSON. APIs pull them into different renderings.

Structure: A headless CMS consists of three elements:

• A database back end
• A web-based user interface
• An API through which content is made accessible

Hosting: A headless CMS is either self-hosted or provided as a service.

Workflow: Content creators use the web interface to create and manage content, and devs query that content via an API and use it to build apps. The layer of abstraction between devs and content creators enables agile workflows. To “publish” content is to make it available via an API.

Example: Using Contentful, a headless CMS platform, you manage content through an interface, and when you publish, Contentful sends your content to a content delivery network (CDN). Assuming you have a valid API token, you can then get your content in JSON after requesting it via HTTP.

What do you get out of the box?

A helpful framework to understand the difference is to look at the out-the-box experience. GraphCMS outlines this well.

When you purchase a traditional CMS, you get the following:

• A predefined theme built on HTML, CSS, and Javascript
• A page builder (optional) for further customization of that theme
• A predefined MySQL database that includes a predefined schema
• Plugins — lots of plugins

When you purchase a headless CMS, you get the following:

• Self-defined schemas included with the headless CMS
• An API end point

And that’s it! It’s up to you to connect the API end point through a data-fetching library and query content to your chosen channel using something like GraphQL. What you’re really getting when you use a headless CMS is freedom.

Dev will choose a box with less in it so that they can connect the headless CMS to their choice of tech stack, such as:

• Jamstack sites
• Static-site generators like Gatsby, 11ty, and Next
• Websites and web apps that use Javascript frameworks like React, Vue.js, Svelte, and Angular

You’re optimizing for flexibility instead of completeness.

What about a hybrid headless CMS? Or a decoupled CMS?

“Headless CMS,” though it has a technical definition, has become something of a marketing buzzword. Vendors that provide CMSs that aren’t truly headless may use the term anyway, making things confusing. Let’s break down a few of them.

In discussions about headless CMSs, you’ll often see the terms “coupled” and “decoupled.” Coupled versus decoupled is another way to differentiate a traditional CMS from a headless CMS. The “body” is coupled to the “head” in a traditional CMS and is decoupled in a headless one.

A simple heuristic: All headless CMSs are decoupled, but not all decoupled CMSs are headless CMSs. That’s a bit of a simplification that, for the most part, holds true.

A decoupled CMS, in some cases, does involve content presentation. But whereas a traditional CMS couples the management and delivery environments, a decoupled CMS pushes content into a delivery environment. In the words of Deane Barker, senior director of content management strategy at Episerver,  a decoupled CMS is “proactive,” whereas a headless CMS is “reactive.” The former “prepares content for presentation and pushes it into a delivery environment,” and the latter “manages content, then just sits and waits for some process to ask for it.”

Similarly, a hybrid headless CMS is one that is decoupled but offers a front end and an API. A hybrid headless CMS uses a headless architecture for delivery but uses a traditional CMS for presentation. It’s a compromise wherein devs get some of the flexibility of an API-driven CMS, but the rest of the team gets a familiar CMS for content creation and storage.

A “pure headless” CMS is built from the start to be API-driven, whereas nonheadless CMS options might just have APIs attached to monolithic architectures. Petr Palas, founder and CEO of Kentico, writes that though a hybrid solution sounds like the best of both worlds, mixing the two is “like mixing oil and water.” As soon as content creators start creating content back in a presentation-first environment instead of API-first, you’ll start to create content silos again.

Why devs choose a headless CMS

Devs choose to use a headless CMS because the separation of “head” from “body” provides benefits that a traditional system, at an architectural level, can’t match.

Whereas a traditional CMS locks you into a particular framework and tech stack, a headless CMS frees devs to use the technologies they prefer. Further, long-term use of a traditional CMS can create hard-to-manage content silos spread across systems.

Flexibility

The top reason devs choose a headless CMS is flexibility. The head-turning benefit is that devs can use any website-building framework they want because they’re not tied to the traditional CMS. In a Kontent survey, more than half (55%) of developers cited this feature as an advantage of using a headless CMS.  

That flexibility pays off in numerous ways:

• Front-end engineers aren’t dependent on back-end engineers when they want to make presentation changes.
• Devs can even swap out parts of their stack or switch frameworks.
• Upgrades are easy (or at least easier).
• You can integrate more tools. Because you aren’t limited by a traditional CMS, you can integrate tools that make you and other teams, like your marketers, happy.

Your system will also be flexible enough to put the right code in the right place. Barker points out that you might be hesitant to include client-specific configuration and theme files, such as text-string translations, noncore CSS, and HTML snippets, with the code files you put into source control. With a headless CMS, you can manage those elements and reference them dynamically.

Speed

A headless CMS doesn’t render content, making it faster. Instead, specialized tools handle rendering, which makes for a faster experience overall.

This speed extends outside the dev team: A headless CMS enables content creators to add and update content, trusting that the content will spread to every device, hassle-free.

Assuming you have the resources, you can also spin up a website much faster. APIs enable teams to treat web development and content creation “as a service,” meaning separate teams can spin up changes and trust that those changes will carry through. You don’t need as much back-and-forth.

Portability

A headless CMS treats content like data, which makes it portable between formats and channels. Devs can more easily manage content across websites and apps.

Remember, a headless CMS is fundamentally reactive, meaning you create content and wait for a device, any device, to request it. Contentful, for instance, has a synchronization API, which is great for mobile apps. Even if users have a poor connection, the synchronization API will ensure content remains up to date.

Centrality

A headless CMS stores content in a centralized hub. That means editors can apply edits across devices and channels with one change. Content will be in sync with itself. Rather than recreate content again and again for each channel, you can create once and distribute everywhere.

Also, whereas a traditional CMS tends to sprawl across a web of features and plugins, a good headless CMS will define the operations that its API supports. That makes it easy to onboard new devs to your CMS.

Cost

Choosing a headless CMS avoids a lot of technical debt before it even starts to accumulate. Content silos that cause rework and repetition are less likely to be an issue. Plus, if redesigns or migrations become necessary, you can minimize their costs because the changes aren’t tied to the CMS.

Security

A headless CMS has only one point of connection — the API endpoint — so the surface area for attack is smaller.

Why wouldn’t you choose a headless CMS?

It’s important to note here that, despite the popularity of headless CMS platforms, the primary use case for websites is “single repository, single website” and most traditional CMS platforms handle that use case well. In the previously mentioned Kontent survey, developers cited four major disadvantages to using a headless CMS:

• 40% said that using a headless CMS required a dependency on web developers (developers are saying this, mind you).
• 38% said that using a headless CMS required a similar dependency on microservices.
• 35% said that headless CMSs lacked marketing capabilities.
• 31% said headless CMSs lacked personalization capabilities.

It’s worth noting that in this survey, developers had the option to say there were no disadvantages to using a headless CMS (and 15% said that).

You can take the first two reasons and generalize: A headless CMS is a technical strategy. If you don’t have the developer resources, it might not be right for you.

The state of the headless CMS market

According to a ReportLinker study, the headless CMS software market was worth more than $300 million in 2019. The same study projects that the market will reach a valuation of $1.6B by 2027.

The shape of the market is hard to define because everyone wants a piece of it. As we said above,  headless CMS has become something of a marketing buzzword, so you can’t always trust a vendor’s website copy to describe what is and isn’t a headless CMS.

Emily Pfeiffer, senior analyst at Forrester, breaks down four ways a vendor might claim that their CMS is headless:

1. “We’re a legacy monolithic platform with extensive functionality, and we have spun off pieces of our offering into separately implementable microservices.”
2. “We are a commerce platform, and we have separated our front end (or CMS or experience layer) from our back end (commerce engine or business management tools) so you can implement either or both.”
3. “We’re a commerce tech provider that has containerized our offering into microservices.”
4. “We are a commerce tech provider that built API-first architecture. There was never a full platform approach but rather a collection of services that may be enabled in any combination and order. Maybe there is no front-end experience layer included with our solution at all.”

‍

To cut through this confusion, let’s turn to a previously referenced expert: Episerver’s Deane Barker. Barker has a good taxonomy that at least offers some clarity. He breaks the types of headless CMS technologies into four categories:

1. Pure Headless CMSs
2. CMSs with Specific Headless Subsystems
3. CMSs with Good APIs and Extensibility
4. Enterprise CMS

This framework makes it easier to categorize headless CMS platforms you encounter and match them to your needs.

Pure Headless CMSs

Barker writes that “intentionality” is a differentiating point when it comes to finding a headless CMS. As long as a decade ago, CMS developers were building systems that resembled headless CMSs, in that they included an administration system and a relational database. Presentation was separate and distinct.

In a sense, then, headless CMSs hark back to how CMSs were originally built. But pure, headless CMSs are designed nowadays with intentionality, deliberately made to honor and leverage the decoupling of front and back end. Barker points out Contentful (a SaaS service), Prismic (a hosted service), and Directus (an open source service) as examples.

CMSs with Specific Headless Subsystems

These CMSs are ones that have traditional presentation systems but “gesture towards headless usage.” That gesture typically includes headless functionalities via API.

Barker wrote in 2017 that the market will “see this [category] more and more” and his prediction has since proved correct with the rise of hybrid headless CMS systems, such as Magnolia CMS (open source), Crafter CMS (open source), and Core dna (SaaS).

CMSs with Good APIs and Extensibility

This is where, as Barker writes, “things get blurry and weird.” The thing is, most CMSs have APIs that can pull content from outside the CMS. In a sense, a CMS that can do so is headless. And if the API is actually fairly advanced, some vendors might have a legitimate claim behind their decision to call their product headless. “Headless Drupal,” for instance, is likely something you’ve heard multiple times before.

Enterprise CMS

These CMSs are the most traditional ones, the CMSs large companies entrust to manage content. According to Barker, these CMSs are “management-focused” — so much so that what little capacity they have for presentation is dedicated to making administration easier. Technically, enterprise CMSs also include remote APIs, but most enterprises are wary of public web serving.

These systems are primarily concerned with managing content and have very little capacity for content presentation beyond the administrative interface itself. These systems are so management-focused that most presentation functionality is only intended to make management and administration easier. Examples include Documentum, Alfresco, Nuxeo, and SharePoint.

Don’t lose your head

The headless-CMS market is exploding in popularity, and many vendors will try to convince you they’re headless when they really just have an API. Don’t lose track of the features you want and what platforms can really deliver on your needs. A traditional or hybrid system might end up being best, but make sure that you know what you’re getting.