There was some buzz in my channels about Reservoir, the headless Drupal 8 distribution which had its genesis in Acquia's office of the CTO. It has some top people on it, like Wim Leers and Ted Bowman.

I was cautious at first, as my experience with distributions hasn't always been good. They are usually a snapshot of a solution to someone else problem:

• features are built from a different set of assumptions to mine,
• I end up dealing with bugs in features I don't even use,
• distributions are often really complex,
• they can lose sex-appeal to their maintainers, and get stale,
• they add product lock-in through feature abstraction and complexity,
• you inherit architectural debt.

And you don't need someone else's architectural debt, you'll have enough on your own.

Why Reservoir is different

Reservoir nails a very specific use-case. It is a product that leverages the general maturity of Drupal 8 as a content management system, serves a specific use-case, and stays safe from the scope creep that end-user facing products are often victim to.

Installation

I'll leave that to the documentation - it's a pretty simple project to set up. Wim Leers has short demo on Vimeo that will clear up any confusion.

I installed with composer create-project acquia/reservoir-project try-reservoir --stability=alpha and then added in geerlingguy/drupal-vm to the resulting composer.json file.

What's in the box

A profile

First thing, it's a Drupal profile. It will install some config and then a module called reservoir_ui, which does a bunch of things, some of which seem opinionated:

• Provides routes for API documentation features.
• Removes a lot of routes that are assumed redundant, like admin/appearance.
• Alters some route paths to create a unified path experience. eg /admin/people/roles becomes /admin/access/roles and so on.
• A few misc CSS, Javascript and interface tricks.

(Only) four contrib modules!

This is unheard of for a distribution, and says a lot about how focussed Reservoir is as a product.

• jsonapi - JSON API provides a best-practice implementation of the {json:api}.
• openapi - Open API helps you use tools like Swagger and Paw to inspect your web services.
• schemata - Schematic supports content serialization into formats like JSON. 
• simple_oauth - Simple OAuth facilitates the use of the OAuth 2.0 Server, the go-to PHP library for OAuth.

Afterword

The great value of a project like Reservoir is that the diamonds are scattered on the beach. The tools and configuration are readily discovered and understood, so that they can be leveraged in other projects.

You can see how easy it would be to add in extended content moderation and media handling, but I hope these features are kept out of scope. Other projects like Well can easily handle wider use-cases.

Perhaps the only disappointing thing is that, if you have a mixed-use Drupal site (ie, some front-end required) you can't easily bring all of the features of Reservoir in your Composer file without some tricky overrides.