Headless CMS explained in 5 minutes

Should you adopt the newer “headless” approach to content management? Or stick with a traditional, monolithic system.

While Content Management Systems (CMS) have been around for a long time, there have been some big changes in what’s on offer lately. Let’s explore the differences between the two approaches and look at how Sanity is an evolution of both.

A headless CMS is a content management system that provides a way to author content, but instead of having your content coupled to a particular output (like web page rendering), it provides your content as data over an API.

The “head” relates to where your content ends up, and the “body” is where your content is stored and authored. This might sound a little strange at first, but the point of a headless CMS isn't that you don't want or need a head, it's that you get to pick and choose which heads (outputs) you send your content to.

In the last few years, we have seen an uptick of CMSes that try to be more flexible in their ways of making content available. These are usually called “Headless” or “API-first” CMSes. Some of them market themselves as “Content infrastructure,” “Content Hubs” or even “Content as a Service.” However, when you take a closer look, they all pretty much boil down to some database backend with a web-based user interface, and content made accessible through an API.

At Sanity we see today’s headless CMS systems as an evolutionary step that leads to an even better way of managing content – where structure is truly flexible, content is treated like data, and editors work in tailored real-time collaboration environments.

As opposed to headless, a “traditional CMS” is software that you either install and have to manage on your own, or on a managed server environment. Traditional CMSes are also called “monolithic” because they pack all the functionality and assumptions for how you want to work into a single system. Traditional CMSes often provide a “What You See Is What You Get” (WYSIWYG) content editing interface because they only have one context for presenting the content – usually a web page.

As a response to the introduction of headless CMSes, some of the traditional CMS vendors have built APIs on top of their systems and market them as “decoupled.” The decoupled approach promises both website rendering capabilities and the flexibility of headless, however, the catch is that decoupled CMS APIs are heavily influenced by a model built for a single website. When it boils down to it, this is a form of coupling and restricts the amount of contexts that your content can reasonably be applied to.

• Decoupled CMSes are adding APIs on top to serve content
• Headless CMSes are API-exclusive

A headless CMS works by:

1. Giving editors an interface for managing content.
2. Providing that content via APIs for developers to query and build applications with.

Most headless CMSes are offered as a Software as a Service (SaaS), meaning that your editors will have to log into a web application and that the APIs are hosted in a cloud-based backend. Some headless CMSes will let you host the whole solution on your own server and database. In this model means you have to do your own scaling and operations.

Sanity lets you host the react-based customizable editing interface yourself, and you get the no-ops and scaling-friendly advantages of a hosted real-time backend. In many ways Sanity is a superset of a headless CMS – because it’s more flexible, offers real-time collaboration, and it treats your content (even rich text) as data. You can use it power products of any kind.

Traditional CMS architectures have to spend resources on content editing, and content rendering. A headless CMS has an advantage over traditional alternatives because it doesn’t have to deal with the rendering side of things. That’s left to other more specialized parts of your stack.

Truly headless content isn’t tied to a single presentation concern (e.g. website), so it can find an audience across multiple channels. You can use a headless CMS to manage content for apps and websites. You can even manage your internal/admin content in the same place and extract more value from it that way.

Because headless content is served over APIs, developers can choose their own frontend tooling. If you’d prefer to work with Javascript instead of PHP or Ruby, you can do that. You can also interchange parts of your stack, or move from one framework to another without affecting the CMS.

Headless lets you manage your content from a single source of truth, change developer tools at any time, and benefit from sending your content to high-performance cloud-based hosting and build services like Vercel and Netlify.

Because headless content is separated from the presentation layer it’s a smaller area of attack.

They’re a popular choice in high performing “Jamstack” sites and work with static-site-generators like Gatsby, 11ty, and Next. They can also be used for web apps and are popular with modern Javascript Frameworks such React, Vue.js, Svelte, and Angular.

A well-designed headless CMS won’t be geared towards a page-based content structure (that should be easy to create, but optional). If this is the case, you can manage content for any product or service: voice assistants, digital kiosks, print, websites – all from the same place.

Some headless CMSes are flexible enough to be provisioned as an E-commerce back end. With Sanity you can also integrate headless content with existing E-commerce platforms and product inventory management systems like Shopify and SAP Hybris.

There are a lot of options out there, and it can be challenging to navigate their many features. We think it’s best to aim for a CMS that can let you grow, and be adapted as your needs evolve. Here’s a list of questions you can ask yourself in order to better evaluate the field:

• Can I create the kinds of content structures I really need with it?
• Do I want, or need to, look after content hosting and maintenance myself?
• Will my content be stored in a secure and privacy compliant manner?
• Would real-time editing and collaboration improve my workflows?
• Will my rich text content be locked to HTML?
• Can I scale my content ops without falling off a price cliff?
• How does it manage files and image assets?

headlessCMS.org offers a fairly comprehensive list of headless content management systems. It’s geared towards Jamstack sites, but a few of them are like Sanity, and can be used for applications outside of the Jamstack.

To better understand the value proposition of a headless CMS it’s necessary to know more about APIs. API stands for Application Programming Interface, which in this context means that you get content in a way that is easier to integrate with existing or new software solutions. Usually, you do this by sending the headless CMS a network request to an API endpoint. This network request is pretty much the same thing you do when visiting a webpage, but instead of a web page, you get a list with the post’s contents back:

// An example of content output in the JSON format
// from Sanity.io’s API

{
    "_createdAt": "2018-04-25T11:21:25Z",
    "_id": "XXXXXX",
    "_type": "company",
    "logo": {
        "_type": "image",
        "asset": {
            "_ref": "image-2bfd3a-sanity-logo-svg",
            "_type": "reference"
        }
    },
    "slug": {
        "_type": "slug",
        "current": "sanity"
    },
    "title": "Sanity.io"
}

Developers then use this information to build software. Most of today’s developers are used to programming with APIs and prefer them because it leaves them in control of how to build their systems. Some CMSes like Sanity also let you change content through APIs. API is a pretty generic term and goes beyond the world of CMSes and the World Wide Web. Therefore, it can be useful to zoom into the two most-used types of APIs when it comes to content management: REST and GraphQL:

APIs can be more or less flexible when it comes to making products on top of them. Traditionally, Headless CMSes have offered REST APIs. They structure the content behind multiple URLs (e.g., /posts /authors /images). Developers have to stitch multiple requests with the IDs of the different content types together. REST APIs can be great for simple data structures but tend to get time-consuming to use when your content models are more complex. It’s also more laborious to change or fit these APIs for different uses.

Facebook developed GraphQL as a response to the less flexible REST convention. It lets you query the API with the fields and relationships you need for each occasion, almost like what you can do directly with a database. It’s also easier to implement new fields and content types as your system matures. Sanity offers GraphQL API with tagged versions so that you can set up different endpoints for different applications.

Sanity stands out from the crowd because it offers GROQ: the most powerful and flexible API of any of the CMSes. GROQ stands for Graph-Relational Object Queries, and lets you:

• Get exactly the content you need in any way or form you need it
• Reduce development time – it’s easier to make decisions about the content model
• Make a document with an entirely new content model and have it instantly available in the API without any deployment or code changes.

The reason we care about good and flexible APIs is they can break the bottleneck that makes it hard to reuse content across channels. In other words, having good APIs on top of structured content makes it portable. But why is that a concern?

Now – and increasingly so going forward. Organizations and businesses need to be increasingly available in multiple channels - be it different websites, apps, voice assistants, or even printed material. Multichannel presence puts a new demand on how content should be managed and delivered. Using a headless CMS and having your content available through APIs is a good start. However, you also want that content structured in a way that makes it easy to use and adapt.

With this in mind, we find it puzzling that nearly all modern headless CMSes store rich text content as HTML. It’s fine when all you do is to deliver content to a web browser, but it’s not a great multichannel storage format – parsing it into other formats can be difficult and unpredictable.

That’s why Sanity designed the Portable Text specification for rich text storage. Editors still get a familiar editing experience, but developers get a more predictable format that is easy to tailor to different display contexts. It’s highly customizable. You can:

• Insert custom made content blocks inline.
• Choose how editors should insert copy-pasted content.
• Direct how the text should be visually presented.
• Allow for deeply-typed content structures where relationships between types are possible within, and on top of, rich text.

Practically, it means that you can link to some internal document and have Sanity index it. It then prevents you from accidentally deleting other documents linked to that document and even lets you query those relationships.

A headless CMS gives editors an interface for easily managing content, while providing APIs for developers to build applications, making it simpler and faster to store, edit and publish content. They differ from traditional and decoupled CMSes because they are API-exclusive, and have nothing to do with content rendering. Choosing a headless CMS

Sanity’s features go beyond the offerings of popular headless CMSes, and the older monolithic CMSes on the market. Here’s why:

• You get real-time collaborative editing out of the box
• Content structures are truly flexible
• Rich text content is HTML-free. We’re the only platform that treats content as data.
• You get a fully open-sourced and standalone editor built in React
• You get a full API-suite with the same backend capabilities as Sanity Studio

Sanity is a perfect fit for teams that need a way to manage content alongside legacy in-house systems, serverless AI content augmenting services, and digital products of any kind.

Set up a Sanity project

For the past year I've been obsessed with digging through and testing out different #headlessCMS for the #JAMStack comparing feature sets for editors, DX, extendibility, etc. Honestly by far I think @sanity_io stands WAY out and I can't believe how mature the product is! @kevinpmcaloon - Jun 18, 2019