Headless CMS: when content lives apart from the site

A headless CMS is a content system with no website of its own: editors change entries in an admin, and sites and apps get them through an API.

When the site and the admin grew together

An ordinary CMS such as WordPress is a monolith: the admin, the storage and the site (the theme) are in one program. That is comfortable while you need one site, exactly as it is. But suppose you want to write the site with a modern tool from the last lesson and keep a familiar admin for the editor. Or show the same content on a site and in a mobile app. A monolith can’t do that: its site and its admin are inseparable.

Without a head

A headless CMS cuts the monolith in two. The “head” is whatever shows the content to a visitor: a theme, a site, an app. It’s cut off, and the “body” stays: the storage, the admin and an API (REST or GraphQL, which we met in part 6). A site, an app or anything else asks the API for the content and draws it however it likes.

What you get:

• Freedom for the site. It can be written with any tool that can read an API, for instance the generator from lesson 5.
• One source, many channels. The same entries are shown by a site, an app and a voice assistant.
• A comfortable admin for the editor: a form with fields, not files and Git.
• Safety. The admin and the storage don’t stick out beside the site, and the site itself can be static.

What it costs:

• the site has to be built: in WordPress it came in the box;
• there’s one more system to maintain and to connect to the site (lesson 7);
• previews of edits (“how will this look?”) don’t work by themselves and have to be set up;
• the price of cloud services grows with the number of editors and requests.

A type, entries and a request

Work with a headless CMS starts from the content model of lesson 1. For a service you create a type (also called a content type or a schema): a list of fields and their kinds.

{
  "type": "items",
  "fields": { "title": "string", "text": "text", "price": "string" }
}

The editor fills in a form built from this schema and saves entries. The site asks the API for them, and the answer is JSON with the same field names:

const response = await fetch('/api/items');
const items = await response.json();   // [{ title: '…', text: '…', price: '…' }, …]

You know this request from part 5. A site makes it either in the browser when a page opens, or at build time, and puts the result into finished HTML (this is what generators do, lesson 7). For two languages, the fields are repeated (title_en, title_es) or the entry gets a translation linked to the original. In the API they arrive under their own names, and the site picks the right one.

Check yourself: what changes on the site if the price is corrected in the CMS?

The price changes in the entry itself. The site sees the new one when it makes its next request or when it’s rebuilt, depending on the setup. The editor changes the text, and nobody touches the site’s code.

Where the content lives: five systems and three places

There are dozens of systems, but the easiest way to compare them is by the main question: where is the content stored? Choose an option in the diagram and follow the path of a single edit.

Files in GitA database on your own serverA cloud service

Examples: Decap CMS (formerly Netlify CMS). The texts sit as Markdown and JSON files in the repository next to the site.

1. The editor changes an entry in the Decap admin
2. Decap makes a commit in the repository
3. The build sees the commit and rebuilds the site
4. The new version is live

Next step of the edit Start over

What is good

• No server and no database: nothing to maintain or break into
• The whole history of edits is in Git
• Free, or nearly

What it costs

• The editor has to sign in through a Git service
• Complex links between entries are awkward
• Every edit is a rebuild of the site

Text alternative: A headless CMS keeps its content in one of three places: files in Git (Decap CMS), a database on your own server (Strapi, Directus), or a provider’s cloud (Sanity, Contentful). An editor’s change travels from the admin through the store to the API or the build, and on to the site. The closer the store is to you, the more control you have over the data and the more upkeep you do.

• Files in Git: Decap CMS (formerly Netlify CMS). The admin edits Markdown and JSON files right in the site’s repository, and every edit is a commit. There are no servers, the price is zero and the history is in Git. It suits small projects.
• A database on your own server: Strapi and Directus. Strapi is written in JavaScript: you describe types with the mouse, and it gives you an API at once. Directus sits on top of an ordinary SQL database (remember part 7) and shows it in an admin with an API. The data is yours, and roles and relations can be complex. The server, the updates and the security are on you.
• The cloud: Sanity and Contentful. Sanity offers a “studio” for editors built into your project, and a query language of its own. Contentful is a cloud service for large teams. The start is quick, previews and teamwork are built in, and the provider stores the content. For a project with personal data that raises a question (part 7), and the price grows with the project.

We state no prices: they change, and the place to look is the service’s own site.

How to choose

Three questions, as before: how many editors there are and who they are, what the budget is, and what data the entries hold. One editor and a small budget: Decap, or even plain files. Complex relations, roles and control over where the data lives (in a region you choose, say): your own server. Many editors, a quick start, and no data about people in the entries: the cloud. The decision is made in lesson 8, together with the rest.

Practice

You’re in 2022: the site and the content have moved apart into different services. Describe a content type for a service, add an entry and write a request that shows the services on the page. The server is simulated, because the sandbox has no network, but the request is exactly the one a real server would get. Pick where your CMS would live, and explain the choice.

What was wrong with 2022

The cloud services are usually American companies, and their content sits on servers you don’t control. If the entries hold personal data, you’re still the one responsible: the GDPR’s rules on transfers outside the EU, and the US state privacy laws, make “where is it stored, and who processes it?” a question to answer before you choose. Many providers let you pick a region and sign a data processing agreement; ask for both. This is general information, not legal advice. Russian teams meet the same question in its strictest form, because Russian law requires personal data of Russian citizens to be stored in Russia, so they often install open systems such as Strapi or Directus on their own servers. Ask yourself in advance where the data lies, and who could stop handing it over.