Now that decoupled Drupal has permeated the Drupal community, even to the furthest extremes, articles (including my own) introducing concepts and how-to tutorials describing how you can build your first decoupled Drupal architecture are ubiquitous. As a matter of fact, decoupled Drupal now also has a book on the subject as well as an annual conference dedicated to the topic. Particularly with the JSON:API module in Drupal core as of 8.7.0, decoupled Drupal out of the box has never been easier.
But despite the brilliant spotlight shining on decoupled Drupal from all corners of the CMS industry, there are lesser-known secrets and hidden treasures that reflect not only the innovative character of the Drupal community but also some true gems that can accelerate your decoupled Drupal implementation. Whether in the area of web services or the category of Drupal modules that extend those same web services, there are myriad components of the decoupled Drupal experience that you may not have heard of before.
In this multi-part blog series, we’ll delve into a few of these concepts in this companion piece to the recent session I (Preston So, Editor in Chief at Tag1 Consulting and author of Decoupled Drupal in Practice) gave entitled “Secrets of the decoupled Drupal practitioner” at DrupalCon Seattle in April. We’ll first venture through a rapid reintroduction to decoupled Drupal before moving progressively up the stack, starting with web services and ending with some of the consumer tooling available to help you maintain high velocity.
A quick introduction to decoupled Drupal
In short, monolithic Drupal consists of a contiguous Drupal architecture that cannot be separated into distinct services. In other words, the default Drupal front end is inextricable from the larger Drupal monolith because of all the linkages that require the front end to remain coupled to the back end, including data references in the theme layer and other tools like the Form API, which allows for the rendering of forms in the Drupal presentation layer according to certain back-end logic.
Defining decoupled Drupal
The simplest definition of decoupled Drupal is also one that adheres to the larger definition of decoupled CMS (and an exhaustive definition is also available in my book Decoupled Drupal in Practice). In short, a decoupled CMS is a content or data service that exposes data for consumption by other applications, whatever these applications are built in, including native mobile, native desktop, and single-page applications. Whereas a single Drupal site could serve a single consumer, in today’s landscape, many practitioners are implementing a single Drupal site that simultaneously acts as a repository for a wide variety of consumers.
The original iteration of decoupled Drupal came in the mid-2010s with the advent of progressively decoupled Drupal. In this paradigm, rather than separating out the front end into a separate implementation, a JavaScript framework could be interpolated into the existing Drupal front end and have access not only to ES2015 capabilities but also certain data Drupal makes available to its presentation layer.
Universal JavaScript
With the proliferation of Node.js and the enablement of server-side JavaScript, Drupal began to be relegated more to concerns surrounding API provisioning and structured content management, while JavaScript application libraries and frameworks like React and Vue.js could take over for all rendering concerns, not only on the client side but also on the server (for both progressive enhancement and search engine optimization purposes).
A typical architecture that implements decoupled Drupal in conjunction with a universal JavaScript application (shared JavaScript code for rendering across both client and server) would facilitate the following interactions: During the initial server-side render executed by Node.js, the application fetches all data synchronously from Drupal to flesh out the render that will be flushed to the browser. Then, when the client-side bundle of the application initializes, the initial render is rehydrated with further asynchronous client-side renders that retrieve updated data from Drupal as needed.
There are many risks and rewards involved in implementing a decoupled architecture of this nature, especially in terms of architecture, developer experience, security and performance, and project management. For more information about these advantages and disadvantages as well as more detailed background on decoupled Drupal, consult my new book Decoupled Drupal in Practice (Apress, 2018).
An alternative API: RELAXed Web Services
While JSON:API and GraphQL have seemingly received all the airtime when it comes to web services available in Drupal, there is another web service implementation that not only adheres to a commonly understood specification, like JSON:API and GraphQL, but also enables a variety of new functionality related to content staging and offline-enabled website features. RELAXed Web Services, a module maintained by Tim Millwood and Andrei Jechiu, implements the Apache CouchDB specification and is part of the Drupal Deploy ecosystem, which provides modules that allow for rich content staging.
An implementation of CouchDB stores data within JSON documents (or resources) exposed through a RESTful API. And unlike Drupal’s own core REST API, now mostly superseded by the availability of JSON:API in core as of Drupal 8.7, CouchDB implementations accept not only the typical HTTP methods of GET, POST, and DELETE, but also PUT and COPY.
RELAXed Web Services occupies a relatively unique place in the Drupal web services ecosystem. The diagram above, which is not exhaustive, illustrates some of the ways in which Drupal’s major web services modules interact. Some depend on only the Serialization module, such as Drupal’s JSON:API implementation (prior to its entry into Drupal core), while others such as GraphQL rely on nothing at all. RELAXed Web Services relies on both REST and Serialization in order to provide its responses.
Thus, we can consider RELAXed Web Services part of the RESTful API segment of Drupal’s web services. The above Euler diagram illustrates how GraphQL, because it does not adhere to REST principles, remains uniquely distinct from other modules such as core REST, JSON:API, and RELAXed Web Services. While all RESTful APIs are web services, not all web services are RESTful APIs.
Installing and configuring RELAXed Web Services
To install RELAXed Web Services, you’ll need to use Composer to install both the relaxedws/replicator dependency and the module itself:
$ composer require relaxedws/replicator:dev-master
$ composer require drupal/relaxed
$ drush en -y relaxed
Fortunately, RELAXed Web Services does not require you to use its content staging capabilities if you do not wish to, but you will need to configure the Replicator user and install the separate Workspaces module if you wish to do so. Without the Workspaces module enabled, the default workspace that is available by default in RELAXed Web Services is live, and we will see in the next installment of this blog series why that name is so important.
The screenshot below displays the RELAXed Web Services settings page, where you can configure information such as the Replicator user and customize an API root if you wish to prefix references to your resources with something different.
While covering the full range of RELAXed Web Services' capabilities is beyond the scope of this first installment, I strongly encourage you to take a look at what is available with the help of the Apache CouchDB specification, as some of the use cases that this approach can enable are unprecedented when it comes to the future of user experiences leveraging decoupled Drupal.
Conclusion
In this blog post, we embarked on a rapid-fire reintroduction to decoupled Drupal for those unfamiliar with the topic as well as a deep dive into one of the most fascinating and seldom discovered modules utilized in the decoupled Drupal space, RELAXed Web Services, which implements the Apache CouchDB specification. In the process, we covered how to install the module before turning to how to use RELAXed Web Services to implement a variety of data requirements in decoupled Drupal architectures in the next installment.
In the next installment in this multi-part blog series, we'll cover how to employ RELAXed Web Services for common needs in decoupled Drupal architectures and some of the intriguing ways in which the module and its surrounding ecosystem enable not only content staging use cases but also offline-enabled features that satisfy the widening demands that many clients working with decoupled Drupal today have on a regular basis.
Special thanks to Michael Meyers for his feedback during the writing process.
For more on decoupled Drupal, see our Decoupled Drupal page.
Photo by Michael Dziedzic on Unsplash