Decoupled Drupal Discovery Checklist

Getting ready for a “headless” or decoupled Drupal project? Before starting on your Drupal discovery workshop, review this quick decoupled Drupal checklist to make sure you cover your bases when planning and reviewing any kind of solutions architecture.

In the beginning, it is easy to get lost in the complexity of a decoupled Drupal project. Right now, you’re just trying to build a mental image of the entire system—and doing your best not to get lost in the nitty-gritty details.

This checklist is meant to help catch as many of the finer points of decoupled Drupal planning as possible without duplicating efforts of broader Drupal or web platform planning checklists.

[Drupal Community: This is also not an exhaustive list, and stands to be improved. Please leave a comment if you have some feedback!]

This discovery checklist is not meant to be a replacement for diligent architecture planning and agile requirements specification during your development and build process.

For now, all you should try to do is get a good idea of the rough size of the project, identify any potential risks, and guide the project to a smooth start.

Decoupled Discovery Checklist


It’s important to start with Why?

  • ❏ Why headless?

If there isn’t a direct answer to that, try some of these questions:

  • ❏ Is Drupal a small service in a larger ecosystem?
  • ❏ Is Drupal serving content across a variety of applications?
  • ❏ Are there plenty of capable application developers and limited Drupal resources?
  • ❏ How does a standard Drupal implementation not serve our purpose?
  • ❏ Who are the key stakeholders who are sponsoring this project? Why do they want it?

Once you’ve identified and confirmed the true motivations behind choosing headless, that will help frame the potential decoupled solution and each of these following questions appropriately.


  • ❏ Will this API be publicly accessible?
  • ❏ How will consumers of the endpoints authenticate to use the data?
  • ❏ Will there be endpoints that server different data authenticated users vs. public users?


  • ❏ What layers of caching exist in front of the endpoint consumer (application)?
  • ❏ What layers of caching are allowed in front of the Drupal layer?
  • ❏ Do cache expirations in Drupal endpoints need to trigger expirations in the Application’s caching layer?
  • ❏ What is maximum time to live (TTL) for content on cached feeds?
  • ❏ What actions should trigger a cache invalidation for an endpoint?
  • ❏ What level of variance will each endpoint have? Role, User, Global?
  • ❏ Are there any SLAs for specific API resources across the Drupal RESTful service?


  • ❏ What content strategy will be leveraged? (loaded question, but many insights gained here)
  • ❏ How many different content types?
  • ❏ How many different content variants need to be served? Content variants may be repurposed or trimmed content which is altered based on the device where it is rendered, e.g. iOS Application vs. Website.


When planning to decouple Drupal to primarily serve a single application framework front-end (perhaps Javascript), it is important to carefully consider how the front-end framework will reproduce the features that you usually leverage contributed modules within the Drupal community. All functionality in contrib modules cannot so easily be transferred to a decoupled application.

To this end, you’ll want to inspect:

  • ❏ How is content structured on the page? Can all content be served by one API resource or will multiple API resources power separate widgets?
  • ❏ For each page type:
    • ❏ Map each set of components to potential APIs.
    • ❏ Markup the likelihood of need for API variance based on the design, either for content-, user-, or personalization-variance.1


  • ❏ What pre-existing infrastructure will this Drupal RESTful service interface with?
  • ❏ Who is responsible for engineering the decoupled infrastructure? Hosting? DevOps?


  • ❏ What load will the decoupled Drupal instance serve?
    • ❏ What is the model for user behavior consuming this APIs? Think logins per second vs. pageviews per second.
    • ❏ What load will each of the consumer applications serve?
    • ❏ Will these consumer applications have their own caching layers?
  • ❏ What volume of uncached (unique) and cached requests will be made per second?
    • Action Item: Build a spreadsheet. A model of requests and cacheability per endpoint will really save you heartache down the road.


  • ❏ How will you control access to your API?
  • ❏ What levels of token authentication will the API offer?
  • ❏ Will the API by throttled with request rate limiting?
  • ❏ Are there required levels of security for certain sensitive data? E.g. credit card transactions

URL Paths

  • ❏ Which system owns the URL Paths?
  • ❏ If the URL Paths are owned by Drupal, how should this be exposed to the consumer? At time of request, or is the application coupled and needs a generated list of redirects (Drupal is the true record)?
  • ❏ If the URL Paths are owned by Drupal, can the Application’s routes be set up to match Drupal’s path pattern (pathauto) logic without interfering with routes outside of the areas Drupal is serving content?


1. This is an indicator of cacheability.