What is Headless Drupal?

headless drupal

If you’ve been to Drupal events recently, there’s a very good chance that you’ve heard the phrase, “Headless Drupal”.

The phrase brings up thoughts of dead horsemen and horror movies.

But, is Headless Drupal scary? And what in fact is Headless Drupal?

We’re going to answer that question in this blog post. Let’s try and understand what Headless Drupal is and who’s using it.

How is Headless Drupal different?

This is the big question, “How is Headless Drupal different from ordinary Drupal?”

In short, with Headless Drupal, a visitor to the website will not interact with Drupal directly.

Often, in Headless Drupal, the visitor will see pages created with Javascript frameworks such as Angular.js or Backbone.js. They will not see a traditional Drupal theme. That’s where the “Headless” name comes from: Drupal’s head / theme is missing.

In this situation, Drupal is mainly used as store for data that is then read by the framework. The normal Drupal interface is still used by users to enter the content that will appear on the website.

However, even the normal Drupal interface could be replaced by other tools such as a mobile app. In this situation, Drupal only provides the logic to run the web application behind scenes.

Where is Headless Drupal headed?

Some of the heaviest users of Headless Drupal have laid out a manifesto with 4 goals:

  • “We want Drupal to be the preferred back-end content management system for designers and front-end developers.
  • We believe that Drupal’s main strengths lie in the power and flexibility of its back-end; its primary value to users is its ability to architect and display complex content models.
  • We believe that client-side front-end frameworks are the future of the web.
  • It is critically important for Drupal to be services oriented first, not HTML oriented first, or risk becoming irrelevant.”

In short, the Drupal should offer many kinds of output, far beyond those offered by the theme system. Drupal should output APIs instead of HTML.

How are Headless Drupal sites created?

The key is to have an API available from Drupal.

The most popular API format provided by Drupal is JSON, because almost every programming language can understand it. Any program which can access the web can use a JSON API.

Earlier this month, we covered the new JSON API that is coming to WordPress. The description of the API given by Ryan, the WordPress developer, applies here too:

“The JSON REST API is a simple but powerful way to interact with [Drupal]. Mobile, desktop and web applications can get data from [Drupal] and do anything you can do via the admin panel. It’s like the admin panel, minus the UI”

A REST API is built into Drupal 8, but not Drupal 7. So, people building Headless Drupal 7 sites need to use a module such as Services or RestWS.

Pantheon had a very good visualization of how Headless Drupal is different from traditional site-building methods:


Any real-life examples of Headless Drupal sites?

A lot of the big Drupal sites are taking the Headless Drupal route. Here’s a sample, taken from this list on Drupal.org. It will also give you and idea of how varied these Headless Drupal implementations are.

I’ve also seen examples of the following also being used:

  • Zurb Foundation
  • Handlebars
  • Meteor.js
  • Java

I could keep on digging out examples all day, but you get the picture. Headless Drupal leads to normal Drupal themes being replaced by dozens of different frameworks.


Are there drawbacks to Headless Drupal?

Yes, particularly before Drupal 8 arrives, we’re dealing with some notable limitations in Drupal 7.

Jeff Eaton listed quite a few via his Twitter account recently:

“Completely decoupling Drupal, right now, comes with drawbacks some projects may not be able to accept. Layout control by editors is much harder. UI localization can’t rely on Drupal, and is harder for admins to tweak w/o front end work. And if the requests aren’t batched effectively, it can incur lots of expensive roundtrips/bootstraps.”

Jared Ponchot followed up on the conversation:

“It’s also worth noting that complete decoupling favors a design system that values complete tailoring over flexibility. Ongoing evolution of content requires front-end focused teams also involved in accounting for resulting evolution in presentation.”

In short, Headless Drupal does often lead to a loss of flexibility. It can limit the options available to those using the site via the normal Drupal admin area and it does rely heavily on the skill of the front-end developers.

Headless Drupal Presentation #1. Building a Drupal-free theme

This Drupal 8-focused presentation at DrupalCon Austin was from Robert Caracaus. Robert shows us how to build a theme using the REST and Angular.JS, whilst entirely avoiding Drupal’s theme system

Headless Drupal Presentation #2: The Business Case

Also at DrupalCon Austin, this presentation focuses on the business case for Headless Drupal. This presentation uses the example of Weather.com’s upcoming move to Drupal. Disclaimer: OSTraining has done some training work related to his project.


  • Steve Burge

    Steve is the founder of OSTraining. Originally from the UK, he now lives in Sarasota in the USA. Steve's work straddles the line between teaching and web development.

0 0 votes
Article Rating
Notify of

Newest Most Voted
Inline Feedbacks
View all comments
Dave Pantzer
Dave Pantzer
9 years ago

This makes me think of the static module, or “sleep at night” CMS, which spins off an HTML-only image of the site to be on the outer server, and leaves the back end to the developer.

Amitai Burstein
Amitai Burstein
9 years ago
Reply to  Dave Pantzer

There’s Zariz — [url=https://github.com/Gizra/zariz]https://github.com/Gizra/zariz[/url]

9 years ago

To sum it up : As Webchick put it in her tweet “Headless #Drupal” (custom front-end, Drupal = content store)

9 years ago

Why not just call it something very intuitive like backend-only-drupal or non-front-end-drupal. The word headless makes me think of dumb terminals and that can be a scary thought 🙂

9 years ago

As the trend of front end frameworks become famous day by day, this headless drupal is very important because drupal is already famous for it’s strong back-end system to achieve any functionality.

9 years ago

If the entire lifecycle of the field is not supported (e.g. rendering by js in the browser) then I can’t see how headless will be useful for anything more than trivial implementations. A ton of manual code/tasks goes into just adding a field. Enterprise apps have hundreds of fields and rules applied to them.

7 years ago

Why is Proofread Bot used as an example if it uses WordPress?

Pallavi Gupta
Pallavi Gupta
6 years ago

Is there any example of website being developed on Angular 2 and Drupal 8 ?

6 years ago

This is an absolutely fantastic article, and makes me proud to be an OSTraining member. It’s worth noting that WordPress now has an API too, which seems slightly adjacent to this idea.

Would love your thoughts, please comment.x