What is an API-first, headless CMS? Why use one?

Like traditional content management systems, API-first CMS let users manage content through a web UI. So how do they differ?

API-first CMS allow developers to decouple content management from content rendering. A coupled CMS, like WordPress, takes care of both: content is stored in a backend database AND rendered in frontend templates using HTML/CSS. So the "head" that's missing from a headless CMS is actually that final "presentation layer":

Your headless CMS isn't concerned about how you choose to display content. It pushes raw content (e.g. JSON or XML) for you to fetch and display anywhere: mobile app, static site, web app, desktop app, IoT device... or all of these at once!

Headless CMS architecture

So why have they become popular? Why are companies like the NY Times, Lenovo, Spotify, Nike, Apple, Microsoft & New Relic using them?

Because the webhasevolved! Frontend tooling & frameworks have exploded. Traditional CMS have become limited in how they display content and are prone to many security exploits. Cross-platform content management has become essential to many projects. Static site generators have resurfaced, opening a content management gap API-first CMS could fill, saving non-technical folks from editing Markdown files.

We have many tools and channels to build digital experiences today. With headless CMS, content can seamlessly follow different forms, not be limited by one.

You can also find a repository of static & headless CMS here, and add to the list with a fork.

Note: We know some clients might insist on using traditional CMS vendors like WordPress or Drupal, for administrative reasons. In that case, know that API-first CMS approaches are still possible: use your coupled CMS as a backend UI to store content, and add a JSON/REST API on top. This'll make your frontend independent of, say, your Drupal install (we'll likely discuss a decoupled Drupal set up soon here). Also, you might want to check out Pantheon's resources on decoupling traditional CMS.

Directus: an open source, headless CMS

We're about to step onto more practical grounds!

For this tutorial, we're using Directus, a free, open source headless CMS. Let's first hear about it from Ben Haynes, Project Lead at Directus:

Directus is a "headless" CMS & API that decouples your content so it can be connected anywhere and everywhere. With a highly extensible DBaaS core elegantly wrapped with an intuitive admin web-application, Directus can mirror even the most complex database architectures. Best of all, this premium framework is completely free and open-source.

When asked what set Directus apart, Ben mentioned a unique combination of 3 key things:

Headless CMS & comprehensive API

Complete control over database schema

Free & open source

Note: paid hosted instances are also available.

We picked Directus because 1) we had never played with it + it clearly fit our content modelling needs, 2) we received a warm response from the founders on their Slack community and 3) we loved their bunny branding.

Lookbook tutorial with Directus, Metalsmith, and Snipcart

This section will show you how to build a "lookbook" e-commerce web app using:

1. Creating our products content fields in Directus

For this demo, we'll include a women & men section in our lookbook. To do so, we'll use the category field we created. See our table data:

2. Binding our headless CMS data to our Metalsmith build process

Our goal here? Use product data from Directus' content API to populate local views (templates, layouts, etc.) and create static assets. Keep in mind that headless CMS aren't strictly bound to this workflow: they aren't opinionated on how you use the data. They only provide a set of tools to deliver it.

Once our build process finishes, we need a folder that can be served as is for users to consume.

We decided to use Metalsmith for the "site" part of this demo. It's got a neat barebones approach, an its modularity fits our use case perfectly. We won't be explaining its inner mechanics for this short tutorial; you can refer to our GitHub repo to see the raw setup.

While writing this, we realized there was no plugin for Metalsmith to interact with Directus during the build. To achieve our humble goal, we built one (open source repo here).The plugin is simple: it fetches data from Directus and creates a file scoped to the build process for each table row (these files aren't in src folder nor in the build one).

From there, Directus data is exposed to our templates, and we can use it to generate our static assets.

4. Deploying our web app on Netlify

Pushing to our repo will now notify Netlify and rebuild/publish the website automatically.

The only problem to fix now is our relative paths, such as the URL we need to declare in our products. We need to find a way for Netlify to inject an environment variable representing its domain for us to use in our views. Let's click on the add button of their "Build environment" section and add a DOMAIN key with the according value:

Now, we need Metalsmith to expose it in our views at build time. There's already a plugin for that called metalsmith-env. We'll install it and add the following part to our plugins object:

GitHub repo & live demo

Closing words on Directus & API-first CMS

Recently, we've seen more developers craft interactive e-commerce experiences with our product (like this one). Choosing a headless approach can be a smart for such projects, so I hope this lookbook demo inspires others to do similar stuff!

I encourage you to give Directus a try if you're looking to build something with an open source headless CMS. Integrating it was super straightforward, and the product offers an A+ UI/UX. The Directus API documentation was also top notch.

This whole integration took me more time than expected—about 8 hours. That's mainly because I got caught up in the fun parts (building a Metalsmith plugin, giving more love to the live demo). We could have pushed a few things further too! Solidifying the plugin, for one. Creating more content types in Directus like product variants, for instance, would have been a nice touch.

I really like the universe of possibilities that "going headless" opens. But while a content management API can often make sense, it's important to mention to not mindlessly default to that. There are still coupled modern CMS options perfect for simple websites. Like always, picking your tech stack is a complex process! ;)