Use Cases for a Headless CMS

By Deane Barker

One of the more inventively-named trends these days is the “headless CMS.” I wrote a definition of this term over at the web content management glossary:

A headless CMS is an informal term to mean a CMS which has editorial and management features, but no delivery features. It exposes content via a web service for consumption by other systems.

A headless CMS does nothing but manage content. It doesn’t deliver content to humans at all. Rather, it “delivers” content to an application of some type. Its immediate consumer is code, and it’s assumed that code will reformat the content for final delivery to a human.

It’s more than just a raw database, in that it has editorial features like user-centric interfaces, workflow, object-level permissions, and such. But it’s less than a traditional CMS in the sense that to “publish” something just means: “make it available via the API.”

Yes, we’ve sort of come full circle back to old school content management when we were all just making database queries from the delivery layer. I trust that we’re a little more sensible now than we were back then, and rest assured there are specific reasons for this, some of which I touched on in an older post about decoupled content management, which might be worth reading.

In terms of nomenclature, the “head” in “headless” is most often the delivery channel, but there are a couple interesting side notes here:

  • While the term “headless” is becoming accepted in the usage presented here, I haven’t seen a wholly accepted term for its counterpart – the environment into which a headless CMS publishes. At the most basic level, some might call this a “website.” But, as we’ll see below, there are lots of other scenarios. “Content consumer” seems too general and vague, but it fits in many cases. It’ll be interesting to see what name this develops over time

  • I’ve also seen “headless” used to refer to a CMS without an admin interface. Some organizations will run a full version of their CMS behind the firewall, but a “headless” version – meaning sans edit tools – in their public environment for security. In this sense, the “head” refers to something entirely different, which makes it seem like the term can refer to any significant layer of a CMS that is “lopped off.”

Right now, the player with most visibility (and funding, I’m guessing) in this space is Contentful – a SaaS service designed from the ground-up for this model. You manage content in their editorial interface. When you press “publish,” your content is pushed into a CDN. With a valid API token, you can request content via HTTP and get it back in JSON. Your content is just “out there” in the cloud, accessible from anywhere.

As I noted in a tweet a couple months ago:

At its core, it’s a CDN for structured content objects.

Contentful certainly isn’t the only one here. This wave has yet to crest, and it’s getting more and more players all the time. There’s an open-source PHP system called Directus, another SaaS system called Prismic, and then there’s Akumina, which has an API for using Office 365 as a headless datasource. Someone asked for a list over at Quora and it got dozens of answers.

Given a competent web API, it’s possible to “convert” a traditional CMSs to headless by simply ignoring the delivery layer and interacting with it at the web API level. I’ve heard a fair amount in the last year about “headless Drupal,” for example.

I’m even seeing traditional commercial CMS vendors start to position themselves in this market in order to aggregate buzzwords (ex: here’s a Kentico page which frames that CMS as headless). It might be more accurate to say these systems are “optionally headless,” since their core intended use case assuredly still includes delivery. (Furthermore, if you plan to ignore large parts of a commercial CMS, you have to ask if it’s really worth paying for anymore.)

(Update: it turns out that Kentico Cloud – their headless offering – is completely unrelated to their traditional CMS. Complete new codebase.)

What’s interesting is that the use cases for a headless CMS are getting a little muddled. This is a “new” paradigm in the sense that it’s a reversion of where CMS had been headed – the market has been pushing further and further into delivery for years, and now we’re suddenly retreating into just management? A lot of people have expressed mystification about why someone would want to go headless. We’ve made such progress as an industry, why are we giving up all this delivery functionality?

In the midst of this running discussion, I visited Contentful in Berlin last month. In addition to feeding me some ridiculous schnitzel (at this place), we sat around a conference room and discussed use cases, in the context of what situations to try and sell into. In what scenarios does a headless CMS work well? When does it not?

What might be surprising is that we more or less agreed on this: the use case of a single repository of information feeding a single website is not a great value-add for a headless CMS.

Now, Contentful (as a proxy for all headless CMS) would work fine here. In fact, my Flying Squirrel Book site runs on Contentful and is this exact model: a single repository of content, powering a single website.

But building this on Contentful was basically an exercise to see how well it worked. At no time was this simpler than just throwing up a WordPress install (the site is pretty simple – in fact, the first version of was simply generated from static Markdown using Wyam, which I still absolutely adore).

There’s just not a huge value proposition there. “Single repository, single website” is the most mainstream website use case, and it’s well-covered by dozens and dozens of systems available for free. This is the most common use case of all websites, really. The entire CMS industry has been focused on this use case for over a decade.

The real value of headless CMS – the situations where it can provide unique advantages – are more interesting than this. Peter, Artas, and I scribbled on a whiteboard for an hour and ended up with at least nine alternate use cases where headless CMS can be a good fit and is worth considering.

The biggest group are use cases that arise from channel and source dispersion –

Non-web content publishing, where you’re not powering a website at all. Mobile apps are a clear example. If you have content needs for your mobile app, a web CMS might be overkill and include a ton of functionality that has nothing to do with what you need.

Contentful has some features which clearly cater to things like mobile apps. A synchronization API, for example, which is designed to deliver “all the content that has changed since the last time I checked.” This is perfect for mobile apps with spotty connections and is not something a website really needs to worry about at all.

Multi-channel publishing, where content is being pushed into multiple channels: web, mobile, print, etc. This is a classic content re-use scenario. While most multi-channel scenarios are pretty web-centric, your website might only be one place where your content gets published. Contentful, in this situation, has no idea where the content will end up, and doesn’t care. It’s just standing by to serve content to whatever channel requests it.

Content aggregation, where content from multiple sources is being aggregated in one place to power a website. If your website is comprised of a bunch of different content sources, you could push them all into Contentful to give your developers a single point of access for all of it.

I see this more in the intranet space, but there are situations where multiple content sources need to be “homogenized” at some layer. I call this the “content warehouse” approach. Like a data warehouse, you push content from all over the place into one location. Instead of your website dealing with N different data sources, it has one, into which content is placed through a variety of processes. This eases developer access and training, avoids many latency and performance issues, and provides some fault tolerance.

Closely related to this would be content middleware, which is really a combination of the above two. Content from multiple sources could be combined in Contentful, then pushed to multiple channels. So, in this situation, Contentful becomes the “traffic cop” in the middle that controls the flow of content.

I interviewed Zach Brand from NPR once about their COPE strategy – Create Once Publish Everywhere. This was an example of multi-channel publishing. Zach told me that the strategy eventually morphed into what they informally called CAPE – Create Anywhere Publish Everywhere. Content streamed in from all over the place, was aggregated and managed in one platform, then was requested from multiple other channels.

Visually, it’s a “bow tie” – a broad array of multiple sources focuses content into the “knot,” and an equally broad array of channels fans it out the other side. (I would use the word “bottleneck,” but for the negative connotations.)

Beyond channel and source use cases, there are some even more interesting scenarios –

Development operations support, where “quasi-code” elements are stored in Contentful for use in another system. These are things like text string translations, non-core CSS, even HTML snippets – things which are code-ish, but around which you have a fundamentally different management model than “true” code files checked into source control.

For example, let’s say your SaaS service allows client-specific configuration and theme files. These aren’t core code of the system itself, and they shouldn’t be muddled it with that. However, they do need management tools and processes. These could be managed from a headless CMS and dynamically referenced at runtime.

"Subservient” content management, where content isn’t the main point of the application. In these situations, content is used as part of a larger application that can’t support a CMS directly. For instance, if you have a massive online banking app that has some content for help files or marketing promos or whatever, you can’t just a drop a CMS on top of this. The CMS has to exist apart from the app, and push content into it, as unobtrusively as possible.

We did this for a well-known company with a very large and complex SaaS web application. Every form field in this application had a little question mark next to it. Holding the cursor over it made an Ajax call to a headless CMS – an API-only instance of Episerver, in this case – to retrieve the help text for display. This help text was managed by a documentation group making full use of Episerver’s management and workflow tools, just without an actual website. The content was only published to the API, to appear as mouseover help text.

Temporary content abstraction, where Contentful is used get content “out of the way,” even just temporarily. We’re working on a large application that has some minor content needs, and we really just don’t want to make a decision on a CMS right now, in the face of everything else we have to do. We’re looking at Contentful to just take that decision away and delay us having to make it. It’s a responsible way to “kick the can down the road,” although, in the end, our “temporary” solution will likely work well enough to become permanent.

Structured content segmentation, where Contentful would be used for a certain type of content, among other types. While this means you have two CMSs, sometimes this isn’t a bad thing. A CMS that you (or your marketing department) love might not handle highly structured, relational content well, but could do other things that make it desirable.

For example, you might have a manufacturing website consisting of two major types of content: (1) highly artisanal, unstructured, marketing-style content; and (2) a highly structured and relational dealer database for users to search. If you can’t find a CMS that does both well, then there’s no rule that says you can’t split this content up. Find a highly visual “page management system” for the marketing department (or even code it by hand, if you don’t need to manage it), and then manage the dealer data in Contentful. If the models between domains of content are very different, then use the tool that works best for each and glue them together.

Editorial segmentation, where a subset of editors do a very specific, limited thing, and whom you don’t want to let into the core CMS. Perhaps they just publish blog posts into a larger website, and for this, you don’t need to train them specifically or customize for any specific need they have. Instead, you just show them how to use Contentful and integrate. Not every editor is created equal, and you might not want to incur the training costs or changes necessary to make your uber-CMS work for absolutely everyone. This is a way to put a subset of editors in a simplified interface and never expose them to all sorts of edge features they’ll never use.

Now, note that these are the rational cases for headless CMS. It’s worth mentioning that there’s an irrational case too –

From time to time, we see development groups that simply don’t want to work with a CMS. They’re used to rolling their own systems and are distrustful of anything big and monolithic which they don’t understand. Yet, their editors – the marketing or documentation groups of their organizations – still want the tools of a “real” CMS.

With Contentful, the editors get a CMS, and the developers don’t actually have to work with one. The Contentful API is competent enough to feel like raw database calls, and any competent developer can be throwing around Contentful objects within about 15 minutes of reading the documentation. If that’s even too much voodoo, it’s shockingly easy to serialize Contentful objects into flat database tables in real-time using webhooks.

(Not even kidding – look at this tweet for an example of serializing Contentful objects into simple XML files in about nine lines of code. Give me another dozen lines, and I’d have it serializing to rows in a database table. Seriously – your developers don’t even have to know Contentful exists.)

I don’t know if it’s fair to call this model “irrational,” because some developers have had legitimately bad experiences with a CMS. Perhaps “compromise” might be better? If some people want a CMS and some people don’t, then perhaps this is a third path that keeps everyone happy.

Note that these nine use cases (ten if you include this last one) are situations where a headless CMS works well and where you wouldn’t think to use a traditional CMS. In these situations, you might think, “Well, our use case is weird, so a CMS doesn’t apply.”

We need to re-wire our thinking, in these situations. A traditional CMS might not apply, but there are other options, and the headless model is gaining momentum. Whether or not you need delivery services is up for debate, but you’re always going to need management services. That’s where CMS starts, really. Without management, you don’t have much.

In the end, we can start looking at a headless CMS as something which provides managed content to other systems, behind the scenes. It cares nothing for how the content is actually used. It delivers content to the 50-yard line (no joke: I blogged about this same metaphor 12 years ago…), and hands it off for the delivery layer to take it the rest of the way.

From this paradigm, there’s an entirely new world of things we might do with content, and that’s exciting.

This is item #21 in a sequence of 357 items.

You can use your left/right arrow keys to navigate