DEV Community

Andrew Brown 🇨🇦
Andrew Brown 🇨🇦

Posted on

TL;DR Headless CMS

Its WordPress without the presentation layer.

Imagine you are using WordPress or Drupal, but when you publish your content, It's making that content accessible via an API. A Headless CMS contains no presentation layer. You don't create templates.

How do you access your content? (fetching content)

Since your content is accessible via an API there are 4 ways to access your content:

  • (Pull) API - Making HTTP requests to a URL
  • (Push) Webhooks - An HTTP request is sent to a defined URL with the Headless CMS
  • (Pull) CLI - Command Line Interface
  • (Pull) SDK - A programming library you use within your web-framework.

Who's doing the rendering then? (Application Integration)

You need to fetch content from the API into your destination application, which will be responsible for rendering the content:

Front-end Javascript Frameworks

Probably the most commonly used method will be using a javascript framework such as React.

The way you would integrate a Headless CMS with a javascript framework would be as follows:

  1. Create your React app
  2. Use the Headless CMS Javascript SDK to pull the API render the data however you like with your javascript components
  3. Why would you want to do this? When you have interactive or dynamic content, you will want to intermix your static content.

Web Application Frameworks

So a web-application would be backed by a database and could include a rendering layer.

So for example, at ExamPro we use Ruby on Rails, which by default, includes a rendering layer.

The way we could integrate a Headless CMS with our web-application would be as follows:

  1. Create an endpoint in our Headless CMS to deliver payloads to
  2. Create a new route eg. /api/new-updates
  3. Parse the payload and store the data in our Postgres database
  4. When people view specific pages, it will serve that content

Why would you want to do this? If you are running a monolithic application, you might be rendering marketing pages due to legacy reasons. It's also possible you have paid content, and you want people to sign up before they can access the content. In the latter case, how would you protect the Headless CMS API? Most Headless CMS's allow you with the press of the button to secure the API, so it requires token authentication to access your content.

Static Site Generators

A static site generator is just the view layer extracted out of traditional web-application.

So for example, at ExamPro we use Middleman, which is a Ruby static site generator. It allows us to use Haml, Sass and Coffeescript as well as the Ruby language to automate the creation of static pages.

The way we could integrate a Headless CMS with our static generator would be as follows:
When new content is published to the Headless CMS it will trigger a user-defined endpoint.

  1. The endpoint would send a request to API Gateway
  2. API Gateway would trigger a Lambda
  3. AWS Lambda would trigger a CodePipeline
  4. CodePipeline would pull the latest repo that contains our Middleman code and pass it to CodeBuild
  5. CodeBuild would run middleman build Within our code we would use our Headless CMS's SDK to pull the latest content from the r Headless CMS's
  6. CodeBuild would then send these new static pages to S3 where we have S3 Static Website Hosting
  7. S3 would trigger a Lambda, which would update our CloudFront distribution.

Why would you want to do this? Smallest javascript footprint, no javascript dynamically rendering content which is going to best for mobile users, especially in weak or slow internet connectivity areas.

Third Parties with Cloud Services

A more creative way would be to use Cloud Services such as AWS or Netlify, to help publish content on various social media platforms.

So, for example, let us say I wanted to publish content to We would need to do the following:

  1. When new content is published to the Headless CMS it will trigger a user-defined endpoint.
  2. The endpoint would send a request to API Gateway
  3. API Gateway would trigger a Lambda
  4. That Lambda would use the API to publish a new article

Okay, but when should I use a Headless CMS?

Managing Multiple Customer Websites

Again, its like Wordpress but without the presentation layer. The business value of WordPress is its easy-to-use interface for non-technical clients.

So the idea here is your customer gets their easy-to-use interface.
The developer gets to build the presentation layer in the technology that is most efficient and makes them happy to use.

That means no more dealing with bizarre WordPress templates and functions.

Managing A Single Website For Yourself

You can use it is for a single website, but I question whether its the best use of your time when you can push code. It all comes down to how much content you are producing and what efficiency you will gain having that CMS component. If you're using it for your portfolio website, it's questionable the utility at this stage of development.

Managing A Single Website with Multiple Authors

Again, its like WordPress, so you can create multiple user accounts in your CMS, so there are various authors. You'll also get ACLs (Access Control Lists), and sometimes these Headless CMS's come with some project management tools such as tasks.

Multiple Destinations

If you want to publish to, other social media (that have APIs) and your website, then a headless CMS can save you a lot of time.

The amount of upfront architecting and infrastructure to implement the presentational layer will vary based on your choice of technologies.

How hard is it to build a Headless CMS?

For me, I can roll my own in an hour. I would just create a Rails app, scaffold out some forms and write a few API endpoints and deploy it to AWS Elastic Beanstalk.

That or I could find an off-the-shelf CMS such as SpinaCMS and code in the API myself. I am sure there are also Headless CMS open-source projects you can deploy yourself.

Should you build or deploy your own? That's up to you to decide. At ExamPro our platform is invertedly headless CMS. We have an API endpoint that delivers outlines of our AWS Certification to used by our static generator. It makes sense for us to roll our own because our content is so unique.

I like the idea of a central place for my content, but I want to use Markdown

Great, many Headless CMS allows you to write your content as Markdown.

Why not just use Github as a repository for content?

You absolutely can. If you're a programmer, you can push markdown files to your repo. You'd have to do a lot of engineering with say creating Github Actions. That Github Action or Github App could trigger an endpoint URL as a publishing mechanism. Github wouldn't be able to serve an API like a Headless CMS.

Okay, so where are these Headless CMS? is technically a Headless CMS.

WordPress could be used as Headless CMS with a bit of elbow grease.
I don't know if you can use it out the of the box today, I would think that the WordPress team will make it happen by default.

There is a variety of Software as a Service (SaaS) where you sign up and starting use a Headless CMS such as Agility CMS.

Using a SaaS Headless CMS over Rolling Your Own

As always, you're paying for convenience. I'll use some of Agility CMS feature sets for our example:

  • The API will be highly available and durable (resistant to disaster).
  • The API will be served behind a CDN, so access to content is fast anywhere in the world.
  • With the press of a button, you can require Authentication for your API (eg. content you want to put behind a paywall)
  • Easily define multiple webhooks to push content to multiple destinations
  • Has an SDK so you can use your programming language of choice instead of wrangling with HTTPs requests.
  • ACLs (Access control lists) to say who can edit or view specific content
  • Project Management tools such as tasks
  • Schedule content to be released in the future.
  • Integration with Google Analytics so you can get metrics on the usage of your API.
  • and of course, you get a rich text editor


  • A Headless CMS is like a WordPress that publishes content to an API.
  • A Headless CMS can be thought of as a central repo for structured content.
  • The customer gets to keep their easy-to-use interface.
  • The developer gets to build the presentation layer in their favourite technologies.
  • You can either push (webhooks) or pull (API,CLI, SDK) content

Top comments (4)

toledoroy profile image
Roy Toledo

Great idea. But why would that be better than something that does both. Head + API?

andrewbrown profile image
Andrew Brown 🇨🇦

If you have multiple websites that rely on your information
If you have a single website then it's debatable but it comes down with giving you more flexibility with the presentation layer (front end part)

toledoroy profile image
Roy Toledo

But is that in any way better than just having multiple frontends to a single backend?
I mean, I do like distributed systems, but can you really sell that to a client?

patarapolw profile image
Pacharapol Withayasakpunt

Maybe, because you want to totally customize the look via SPA, which is the Head.

BTW, I have totally rolled one