Decoupling Drupal can be arduous, whether you're developing a Drupal-backed front end or configuring Drupal to be an ideal content repository for decoupled applications.
Adding to the challenge is the fact that there is a lack of definitive starting points, boilerplates, and best practices. But the issue isn't simply that there are so many competing approaches; it's also that there doesn't yet exist an easy starting point for non-Drupal developers who solely want to configure Drupal to be the back end for their front-end applications and get on with development.
Acquia's Office of the CTO is pleased to announce the release of Reservoir, an experimental Drupal distribution developed by Wim Leers (coordinator of Drupal's API-first initiative) and Ted Bowman. Beyond comprising an exceptional starting point for any decoupled Drupal implementation, it is also designed to on-board developers of all backgrounds: a decoupled Drupal distribution and optimal back end for every developer.
Reservoir is a distribution for decoupling Drupal
The welcome screen after installing Reservoir.
In Drupal terms, Reservoir is a minimalist distribution for decoupling Drupal. In more general terms, Reservoir is a flexible and simple tool to build content repositories for any application to consume: it focuses on modeling content, managing content, and interacting with that content via HTTP APIs.
Reservoir deliberately strips out a broad swath of typical Drupal functionality, including the user-facing front end and modules irrelevant to content repositories (such as History, Breakpoint, Contact, Block, RDF, and Views, among others). Moreover, Reservoir includes certain key features that accelerate decoupled Drupal implementations:
- Opinionated selection of API-first or web services modules. Reservoir makes getting started with Drupal as a content repository for other applications much simpler. Rather than Drupal’s own serialization format, it offers JSON API. In the future, we also aim to offer GraphQL support. For Drupal developers: Reservoir includes the JSON API and Simple OAuth modules, meaning you no longer need to configure REST resources and views.
- Auto-generated API documentation. Reservoir automatically generates API documentation as you create and modify content models — and better still, this documentation appears alongside your content while you browse it. You can also download an OpenAPI (Swagger) description and use your favorite tools to generate API documentation. For Drupal developers: Reservoir also comes with the OpenAPI module plus the ReDoc JavaScript library, which is GPL-compatible.
- Tailored user interface. When you install Reservoir for the first time, a convenient welcome tour greets you which points out the three primary tasks one can perform using Reservoir (modeling content, managing content, provisioning HTTP APIs). For most, the complete breadth of capabilities Drupal offers isn't necessary, but Reservoir still enables you to access the full power of Drupal.
Together, these features allow for any developer to start immediately consuming a content repository capable of serving any front end.
Rationalizing Reservoir
Viewing content in Reservoir — in both HTML and JSON API representations.
The plan for Reservoir began roughly eight months ago as an experiment within Acquia's Office of the CTO after discussions at DrupalCon Dublin. We asked ourselves the following questions:
- What would happen if Drupal were stripped down to its bare essentials for decoupled use cases?
- What would happen if anyone could easily configure Drupal to back their own non-Drupal applications?
- What if there was a third installation profile in Drupal core solely optimized for decoupled Drupal rather than the foregoing monolithic implementations?
Since that time, the demand for a solution like Reservoir has only grown considerably. Within Acquia, we were seeing more frequent requests for a starting point for decoupled implementations which would limit the amount of time spent configuring and setting up Drupal. We were also interested in fostering a coalescence of specific best practices centered around the solutions with the most momentum and promise, such as JSON API and OpenAPI.
Furthermore, we were discovering that developers unaccustomed to Drupal were encountering challenges consuming and manipulating Drupal content due to the many knobs and dials one must understand in order to leverage Drupal core’s built-in REST API, as well as its unfamiliar serialization format. The opinionated starting point that Reservoir offers makes Drupal so easy, so accessible, that any developer can ramp up and build a repository in a matter of minutes.
Why we're open-sourcing Reservoir today
Automatically generated API documentation.
Today, we're open-sourcing Reservoir because we see it as a crucial contribution to the Drupal community, even though it remains merely an experimental and unsupported distribution. We resolved to wait until today to open-source this project because we felt that core's web services and contributed modules such as JSON API and OpenAPI were not quite sufficiently mature yet.
Acquia has also been strongly supporting the API-first initiative in Drupal core. In conjunction with those efforts, Acquia has also been contributing heavily to the JSON API (Wim Leers has made dozens of contributions) and OpenAPI (Ted Bowman has spearheaded this API documentation effort) modules.
Reservoir is currently immediately available in two repositories on GitHub, acquia/reservoir and acquia/reservoir-project. Hosting the project on GitHub will lower the bar for developers who might not have ever even heard of Drupal. Here's Reservoir co-creator Wim Leers demonstrating some of the key features of Reservoir:
Reservoir and Contenta
The need for a distribution or installation profile to serve as a starting point consisting of best practices for decoupling Drupal emerged several times during core conversations at DrupalCon Baltimore ("Decoupled from the Inside Out" and "API-first Initiative"). By this point, Acquia’s Office of the CTO had already been working on Reservoir for quite some time.
After DrupalCon Baltimore, a Drupal core idea issue was created, its goal being to add an API-first install profile to Drupal core. The Contenta CMS, built by Mateu Aguiló Bosch (API-first initiative coordinator), Cristina Chumillas, Sally Young, Daniel Wehner, and others, quickly gained traction and momentum.
Contenta has similar goals but different priorities. It chooses to target Drupal developers by situating the default Drupal user interface front and center and including the JSON API Extras module to add even more configurability. In addition, Contenta aims to include extensive default content (which can be disabled) and example front-end applications tuned to that default content aimed at helping non-Drupal developers.
Reservoir is our take: simpler, to the point that non-Drupalists are delighted when they try it.
Together with the larger API-first initiative, we've been hard at work contributing to rapidly maturing modules such as JSON API and OpenAPI. It's our hope that with Reservoir, not only will we aid Contenta by showing how we confronted the same larger issues in another way; we'll also provide another compelling solution benefiting the larger web community. We've had a wonderful history of deep and involved collaboration with the people behind Contenta, and we're excited to see more cross-pollination happen so that Drupal will eventually ship with the best API-first installation profile possible.
Conclusion
The traditional Drupal we know and love will always stick around. Still, many developers nowadays want an optimal and learnable back end that enables them to build front ends independently, even leveraging different technologies on a project-by-project basis. That’s what Reservoir aims to provide: the best back end for all your front ends, no Drupal knowledge required — which also happens to reuse many of the Drupal building blocks we’ve developed over the past decade and a half.
Armed with the insights we've garnered from having contributed to Drupal 8's API-first initiative for well over a year, we're thrilled to present our take on how an API-first distribution of Drupal should look. Reservoir brings together all the functionality that we’ve been helping to mature and enrich in a single easy-to-use package.
Check out Reservoir on GitHub, or install it using Composer, and give it a try — you’ll be up and running in only a few minutes! Please send us feedback and let us know whether this indeed makes the big difference we believe it does. We hope you enjoy using it as much as we enjoyed building it.
Special thanks to Wim Leers and Ted Bowman for contributions to this blog post. This blog post has been updated to reflect corrections regarding available features in Contenta.
