Reservoir

Reservoir is a back end for your front end: a content repository. Uses JSON API and OAuth2.

It's dead simple to use. Log in and there are four tabs:

1. Content: where content administrators administer content
2. API: where client developers can browse the API documentation
3. Content models: where the owner can model content for their needs
4. Access control: where the owner can administer users, clients, roles, permissions and tokens

After installing, you're welcomed by a tour, and you're ready to explore — in fact, you can make API requests right away!

---

How to install Reservoir

The preferred way to install Reservoir is using our Composer-based project template. It's easy!

1. Install Composer

2. Create a Reservoir project with composer

$ composer create-project acquia/reservoir-project MY_PROJECT --stability=alpha

3. In your webhost configuration, point my-project.com to [MY_PROJECT]/docroot
4. Install Reservoir by going to http://my-project.com

Concepts

There are only seven concepts you need to understand, and most of them you already know!

1. Content models
2. Content
3. Users
4. Clients (OAuth2)
5. Roles
6. Permissions
7. Tokens (OAuth2)

The tour starts automatically after installing Reservoir. Afterwards, you can take the tour again by clicking the "Tour" button in the top right corner.

Authentication

Reservoir supports only OAuth2, and only the Password Grant for OAuth2. Why only this grant type? Because Reservoir provides a content repository, and all content must have an author.

The password grant type allows clients (applications and front ends) to interact with Reservoir, but always on behalf of a user.

Before deploying to production

Before deploying Reservoir to production, delete demo material and change the keys.

During installation, Reservoir creates four pieces of demo material:

1. /node/1: demo content, titled "Hello world"
2. /user/2: demo client user, called demo-user
3. /user/3: demo content administrator, called demo-writer
4. /user/4: demo client developer, called demo-developer
5. /client/1: demo client, called Demo app

(The password is identical to the user upon each installation.)

You'll want to:

1. Remove the demo material
2. Replace the auto-generated OAuth2 public/private key pair
3. Refine CORS settings

That's it!

Related projects

There is a rapidly expanding ecosystem surrounding Reservoir:

• reservoir-project: Composer installer for Reservoir
• reservoir-docker: Docker image for Reservoir
• well: Drupal installation based on Reservoir and BLT

Drupalists

If you're already deeply familiar with Drupal's concepts (such as entity types, fieldable entity types, config entity types, entity bundles, text formats, vocabularies, Views …) and you are used to finding your way around the Drupal UI, then you may find Reservoir too limiting.

Reservoir limits itself to nodes ("Content") and node_types ("Content models"). These limitations make it simpler, more understandable, hence simplifying development, maintenance and the mental model.

However, Reservoir still allows you to install any Drupal module to gradually add capabilities (if and when you need them): it's still Drupal under the hood. If you want the most complete Drupal experience, already preconfigured for decoupled use cases, we recommend you try Contenta — it has "Recipe magazine" demo content with multiple demo apps and a "Knowledge Hub" with tutorials.

Reservoir focuses on simplicity (but is limited). Contenta focuses on powerfulness & completeness (but has all of Drupal's complexity).

You can start with Reservoir and expand your insights with Contenta's extensive examples. When starting a project, choose either Reservoir or Contenta, depending on the project's needs (use Contenta if you want vocabularies, comments, media …).

Future

• Support GraphQL once it matures
• Add authentication information to the OpenAPI docs
• Add maintainable mechanism to not expose certain content/config entity types in both API docs nor allow accessing them via JSON API.
• Ensure only users with the content_administrator or client_developer roles can log in.
• Allow users with the client_developer to create and edit roles other than client_administrator and client_developer, and allow them only to grant+revoke non-restricted permissions. This then allows them to define roles (scopes) for clients.
• Make it easy to delete all default content in one go: node 1, users 2, 3 and 4.