Should you Decouple?

Note: This article was originally published on April 29, 2015. Following DrupalCon Nashville, we are republishing (with updates) some of our key articles on decoupled or "headless" Drupal as the community as a whole continues to explore this approach further. Comments from the original will appear unmodified.

One of the major topics of discussion in the Drupal community has been decoupled (or headless) Drupal. Depending on who you ask, it’s either the best way to build break-through user experiences or nothing short of a pandemic. But what exactly is a decoupled architecture?

A decoupled content store splits the content of a website from how it is displayed on multiple independent systems. Decoupled sites are the logical evolution of splitting content from templates in current CMSs. Decoupled architectures started to become mainstream with the publication of NPR’s Create Once, Publish Everywhere (COPE) series of articles. Other media organizations including Netflix have seen great benefits from a decoupled approach to content.

Like many other solutions in computer science, decoupling is simply adding a layer of technical abstraction between what content producers create and what content consumers see.

Technical decision makers face an important choice when evaluating Drupal 8. When an existing site is upgraded to Drupal 8, how do we decide if we should decouple the site or not? Before we decide to work on a decoupled implementation, it’s critical that everyone, from developers and project managers to content editors and business leaders, understand what decoupling is and how to ensure a decoupled effort is worth the technical risk.

Why Decouple?

I’ve seen many people jump to the conclusion that decoupling will solve problems unrelated to a decoupled architecture. Decoupling doesn’t mean a website will have a cleaner content model or a responsive design. Those are separate (though relevant) solutions for separate problem sets.

These are the specific advantages of a decoupled architecture for a large organization:

• Clean APIs for mobile apps: Since the website front-end is consuming the same APIs as mobile apps, app developers know that they aren’t a second-tier audience.
• Independent upgrades: When the content API is decoupled from the front-end, the visual design of a website can be completely rebuilt without back-end changes. Likewise, the back-end systems can be rebuilt without requiring any front-end changes. This is a significant advantage in reducing the risk of re-platforming projects but requires strict attention to be paid to the design of the content APIs.
• APIs can grow to multiple, independent consumers: New mobile apps can be created without requiring deep access to the back-end content stores. APIs can be documented and made available to third parties or the public at large with little effort.
• Less reliance on Drupal specialists: Drupal is a unique system in that front-end developers need to have a relatively deep understanding of the back-end architecture to be effective. By defining a clear line between back-end and front-end programming, we broaden our pool of potential developers.
• Abstraction and constraints reduce individual responsibilities while promoting content reuse: Content producers are freed from needing to worry about an exact presentation on every single front-end that consumes content. Style and layout tweaks are solely the responsibility of each front-end. Meanwhile, front-end developers can trust the semantics of content fields and the relationships between content as determined by the content experts themselves.

Here Be Dragons

At the beginning of a decoupled project, the implementation will seem simple and straight-forward. But don’t be fooled! Decoupled architectures enable flexibility at the cost of simplicity. They aren't without risk.

• One system becomes a web of systems: A decoupled architecture is more complex to understand and debug. Figuring out why something is broken isn’t just solving the bug, but sorting out whether the problem lies in the request or in the API itself.
• Strict separation of concerns is required to gain tangible benefits: As front-end applications grow and change, care has to be taken to ensure that front-end display logic isn’t encoded in the API. Otherwise, decoupled systems can slowly create circular dependencies. This leads to systems with all of the overhead of a decoupled architecture and none of the benefits.
• Drupal out-of-the-box functionality only works for the back-end: Many contributed modules provide pre-built functionality we rely on for Drupal site builds. For example, the Google Analytics module provides deep integration with Drupal users and permissions, "page not found" tracking, and link tracking. In a decoupled architecture, this functionality must be rewritten. Site preview (or even authenticated viewing of content) has to be built from scratch in every front-end, instead of using the features we get for free with Drupal. Need UI localization? Get ready for some custom code. Drupal has solved a lot of problems over the course of its evolution so you don’t have to—unless you decouple.
• The minimum team size is higher for efficient development: A Drupal site with a small development team is not a good candidate for decoupling unless the content is feeding a large number of other applications. In general, decoupling allows larger teams to work concurrently and more efficiently, but doesn't reduce the total implementation effort.
• Abstraction and constraints affect the whole business: The wider web publishing industry still has the legacy of the "webmaster". Editors are used to being able to tweak content with snippets of CSS or JavaScript. Product stakeholders often view products as a unified front-end and back-end, so getting the funding to invest in building excellent content APIs is an uphill battle. Post-launch support of decoupled products can lead to short-term fixes that are tightly coupled, negating the original investment in the first place.

The Heuristic

To help identify when decoupling is a good fit for a client, Lullabot uses the following guidelines:

Decoupled architectures may be appropriate when:

1. The front-end teams require full freedom to structure and display the data.
2. The front-end team does not have Drupal expertise.
3. More than one content consumer (such as a website and multiple mobile apps) is live at the same time.
4. Display front-ends combine data from multiple distinct API sources like CMSs, video management systems, and social media.
5. A project consists of multiple development teams.

If a project meets some of these criteria, then we’ll begin a deep-dive into what decoupling would require.

• Does decoupling also require a complete content rewrite, such as when migrating from legacy "full-page" CMSs? We’ve encountered sites that haven’t made the move to structured data yet and still consist primarily of HTML “blobs.” This scenario presents a significant hurdle to decoupling, though it’s a separate problem from decoupling.
• Does the development team have the time needed to build and document a content API with something like Swagger? Or is using Drupal as a site building (but coupled) development framework a better fit?
• Does the web team consist primarily of Drupal developers, and will those developers continue to support the website in the future? Would the front-end team be better served by Views, Panels and the theme layer, or by a pure front-end solution like React or Angular?
• Is there enough value in decoupling that the business is willing to change how they work to see its benefits?

Decoupled architectures are a great solution - but they’re not the only solution. Some of the best websites are built with a completely coupled Drupal implementation. It’s up to us as technical leaders and consultants to ensure we don’t let our excitement over an updated architecture get in between us and what a client truly needs.

Header image by Daniel Schwen CC BY-SA 4.0, from Wikimedia Commons