Decoupled Drupal

This page is archived

We're keeping this page up as a courtesy to folks who may need to refer to old instructions. We don't plan to update this page.

Alternate resources

In this series we're going to take a closer look at Decoupled (or Headless) Drupal.

We'll start out by talking about what it really means to decouple your website. Then we'll come up with a list of criteria that should be considered when deciding if pursuing a decoupled approach is a good idea for your project. Then, we'll start in planning our decoupled project by talking about the components that make up a solid API. With the fundamentals in place, we'll then talk about making sure your API is documented and tested.

Next, we'll look at a variety of methods in Drupal we have at our disposal to expose data from our site as an API. We'll take a quick look at writing custom code, using Views Datasource, Services module, and the RESTful module to expose data from a Drupal 7 site. We'll also take a look at what Drupal 8 brings to the table to help us build out a REST API without writing a single line of code.

With our API in place, we can turn our attention to a simple front-end blog demo project. We'll start with a Bootstrap template and write a single page Javascript application to handle navigation between current posts and the blog's archives. We're going to make use of a few new technologies that will also be at our disposal in Drupal 8, Backbone.js and the Twig template system. Once our basic single page application is built out, we will take a look at a couple of methods we can use to improve our SEO and the experience of our user's initial page load. In doing this, we'll learn about isomorphic Javascript and clean up our custom Javascript application. Finally we'll take a look at some of the hosting implications and considerations you'll need to address when thinking about launching our newly decoupled project.

By the end of this series, you'll see how easy it is to expose data from our Drupal site as a JSON API, and be itching to try out the latest Javascript framework to build your own isomorphic single page application.

Tutorials in this course
Drupal 7, 8, 9, and 10
More information

If you're interested in decoupling Drupal, there's a good chance you've heard at least some of the buzz in the Drupalverse about "headless" or decoupled Drupal. Or perhaps you watched Dries' keynote from DrupalCon Barcelona or read Dries' blog post about the future of decoupled Drupal. Whatever the case may be, this tutorial and the ones that follow will walk you through building a simple decoupled blog. In Dries' terminology the demo site we'll be building is "fully decoupled." While it would be trivial to adopt similar techniques to build a progressively decoupled site, let's dig a bit deeper into what it means to build a decoupled Drupal site.

More information

Andrew Berry, from Lullabot, has written a great article asking Should you Decouple? Like most architectural decisions there are trade-offs to consider with a decoupled approach. Let's take a look at some of the pros and cons of a decoupled approach. Is it the right choice for your project?

Drupal 7, 8, 9, and 10
More information

There's been a lot written about API design, it's probably not surprising there are several books written about the subject. It also seems like nearly every cloud-based service provides an API to allow access to your data. In this tutorial, we'll attempt to condense this information and answer the following questions:

  • Are there different types of API paradigms?
  • What kinds of considerations do we need to make when building an API for our decoupled site?
  • And, what's this REST thing everyone is talking about?

Let's dig into those questions one at a time.

More information

In this tutorial, I'll introduce the API Blueprint specification and take a look at a few tools we can use to provide documentation and testing for our API.

The tools we'll look at include:

By the end of the tutorial you'll have a better understanding of the API Blueprint specification and be able to use Dredd and Aglio to ensure your API documentation and testing stay up-to-date.

Self-check question: Could you write a script that could be run after every commit that would keep your documentation up-to-date, and provide API test results?

Additional resources

API Blueprint

More information

In this tutorial, I'll show you a few ways we can create a basic API by exposing data from our Drupal site.

The methods I'll use include:

Self-check question: In what situations would you consider using each of these approaches?

Additional resources

Views Datasource

More information

Another popular method of creating an API from a Drupal site is using the RESTful module.

In this exploration of the module we will:

  • Walk through the documentation
  • Use the example code to expose basic entity information
  • Write custom code to expose more complex data

By the end of this lesson we'll have built the final API we're going to use to build a demo application.

Self-check question: Without looking at the repository, can you write the code necessary to expose Drupal menus using the RESTful module?

Additional resources

RESTful —

More information

Core in Drupal 8 comes with a built-in solution for providing creating a REST API without writing a single line of code.

NOTE: We now have a full series on Web Services in Drupal that goes into much more detail about building your API for a decoupled site.

In this lesson we will talk about the core modules that help create a REST API, including:

  • REST module
  • Serializer
  • HAL
  • Basic Authentication
  • and the RESTUI contributed module

Self-check question: Can you find examples in Drupal core of plugins that expose data to the REST server?


  • The video covers creating a node (via POST) twice, using two different versions of the Postman Chrome extension.
  • The REST_UI module has been updated since the creation of this video. Rather than providing unique permissions for users it now leverages entity permissions to determine if a user has access to a particular operation or not.

Additional resources


More information

In this tutorial we'll begin building our simple Javascript blog application. Starting with Bootstrap templates, we'll use a Javascript implementation of the Twig template language to make our blog dynamic. In the course of doing so, we'll learn about Cross Origin Resource Sharing (or CORS). We will also begin to identify some common implementation patterns in our Javascript, and start to refactor our code to improve its organization.

Self-check challenge: Create another sidebar block in our blog that pulls data from Open Weather Map to display the current temperature in your city.

Additional resources

Open Weather Map

More information

Building a traditionally "coupled" Drupal site provides us with a lot of functionality we've so far taken for granted when building our simple blog.

This lesson attempts to remedy some of that by: building a functional pager and a post archive.

We'll also make our blog into an actual Single Page Application (or SPA) by using the client-side router provided by Backbone.js

Self-check challenge: Add a form with select list elements that filter posts (instead of relying on the sidebar links).

Additional resources

Backbone.js Router

More information

One of the historic complaints—and drawbacks—of client-side Javascript applications is that they aren't SEO-friendly. While Google's crawler, in particular, is starting to execute Javascript on pages it indexes, in this tutorial, we'll take a look at a couple other of methods of mitigating this issue.

In particular we'll learn about:

  • What is Isomorphic Javascript?
  • Writing a server with Express.js

Self-check question: In addition to SEO, what are some other benefits of isomorphic javascript?

Additional resources
What is an isomorphic application? — by Juampy NR on

More information

At this point, whether we've decided to use a third-party pre-rendering service or we've written our own isomorphic JavaScript application to serve as the front-end of our website, our hosting requirements have definitely gotten more complex. Let's take a look at the continuum of decoupled site architectures and start to come up with a list of things to keep in mind when considering their hosting requirements.

This course appears in the following guides:
Theming controls the look, feel, and markup of a Drupal site.

Theme Drupal Sites