Repositories

Composer-supported profile

https://github.com/acquia/reservoir

Composer based starting project

https://github.com/acquia/reservoir-project

Acquia BLT configured projects

Existing (fork or try yourself)

https://github.com/damontgomery/well (Reservoir, BLT, Drupal VM)

https://github.com/ba66e77/mrpink (Reservoir, BLT, Drupal VM)

Create your own

https://www.datasmith.net/article/setting-blt-reservoir

Installation notes

Setting up OAuth keys

The web based installer will create temporary keys, but it's likely your system will delete these. To be safe, you can create your own keys.

Let's assume your project is within /docroot like,

.git
.gitignore
docroot
docroot/core
docroot/modules
docs
...

Follow this process to create and configure your own keys. This is based on the README in the simple_oauth module used by Reservoir.

# Create a folder for your keys.
mkdir oauth

# Open that folder.
cd oauth

# Create your private key.
openssl genrsa -out private.key 2048

# Create your public key.
openssl rsa -in private.key -pubout > public.key

You will need to visit /admin/config/people/simple_oauth to set your keys.

# The paths provided must be full paths.
# The following example uses defaults from Drupal VM as seen with Well.
public key: /var/www/[site]/oauth/public.key
private key: /var/www/[site]/oauth/private.key

# Example
public key: /var/www/well/oauth/public.key
private key: /var/www/well/oauth/private.key

While you are here, you might want to increase the expiration time to 1 hour for the access token. 3600 seconds is 1 hour.

Setting up roles and clients

When accessing the site from outside Drupal, a user accesses the API using a client. That client has a defined scope of permissions which defines what they can view and modify.

Create a new role

/admin/access/roles Scopes and managed as roles in Reservoir. This is a set of permissions that a client / user has for creating, viewing, deleting, updating, etc content.

Assign this role permissions (RECOMMENDED)

/admin/access/permissions Roles are not worth much without permissions. Allow the new role to create, delete, etc content.

Create a new client

/admin/access/oauth2/clients Now that you have a role, you can create a new client. This client will pair to your application and allow users to log in through that client.

Assign this client a scope

When creating a client, you will see scopes based on the roles you created earlier.

Create a new user (RECOMMENDED)

/admin/access/users

Create a new user and assign that use to the role you created before. We will use this user to get an authentication token.

Testing the system with Postman

Postman is a free tool for testing requests and responses. You can download it from the Google Chrome store. This should get you started. For more information, please see the list of guides, https://github.com/acquia/reservoir/wiki/Guides-and-Resources.

Authentication

Set an expiration for authentication keys

You will probably want to increase the expiration time for the key so that testing is easier. Go to /admin/config/people/simple_oauth and set the expiration to something longer. 3600 = 1 hour.

Get an authentication token

Create a new POST request for http://local.well.com/oauth/token. With the Body tab, select x-www-form-urlencoded. Add key / values for

grant_type: password
client_id: (get from /admin/access/oauth2/clients)
client_secret: (used when creating the client)
username: (Drupal user)
password: (Drupal user's password)

When you Send the request, you will get back an access token.

API generated documentation

Reservoir will generate documentation for the API for each site. Visit /admin/api

Get a list of articles

No authentication is required. Make a GET request to /jsonapi/node/article You can view the response as JSON.

Create an article

Authentication is required. Make sure your client has the permissions to create articles. Make a POST request to /jsonapi/node/article. Add these two headers:

Content-Type: application/vnd.api+json
Authorization: Bearer (insert your access_token from the token request before)

In the body of the request, you can provide a JSON formatted data object with your new article.

Create (POST) request body

{
  "data": {
    "attributes": {
      "langcode": "en",
      "status": true,
      "title": "Mr Postman",
      "field_body": null
    }
  }
}

This example creates a new article with the title Mr Postman and no body. Send the request and get back the data for that new article.

Delete an article

Authorization is required. See the Create an article section for headers. Create a DELETE request using the UUID of the article and the path /jsonapi/node/article/(UUID)

Update an article

Authorization is required. See the Create an article section for headers. Create a PATCH request using the UUID of the article and the path /jsonapi/node/article/(UUID) The body then provides the ID again along with any information that should change. The response includes that node back,

Update (PATCH) request body

{
  "data": {
    "id": "141962d7-2180-4419-bb8e-a9c1d337aeb2",
    "attributes": {
      "title": "Mr Patchy"
    }
  }
}

Getting ready for decoupled frontend development

Configure CORS settings

Drupal core supports a system for configuring CORS settings. These are necessary if your browser based application will be running with a different origin than the Reservoir site.

You can find the settings in sites/default/default.services.yml under CORS

parameters:
   # Configure Cross-Site HTTP requests (CORS).
   # Read https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS
   # for more information about the topic in general.
   # Note: By default the configuration is disabled.
  cors.config:
    enabled: false
    # Specify allowed headers, like 'x-allowed-header'.
    allowedHeaders: []
    # Specify allowed request methods, specify ['*'] to allow all possible ones.
    allowedMethods: []
    # Configure requests allowed from specific origins.
    allowedOrigins: ['*']
    # Sets the Access-Control-Expose-Headers header.
    exposedHeaders: false
    # Sets the Access-Control-Max-Age header.
    maxAge: false
    # Sets the Access-Control-Allow-Credentials header.
    supportsCredentials: false

In Drupal 8, you can override these settings in two ways.

Configure the site on all environments

Edit sites/default/services.yml and update the values for CORS. You will want to enable the system and then provide your own parameters.

Example

parameters:
  cors.config:
    enabled: true
    # Allow 'Content-Type' and 'Authorization' headers.
    allowedHeaders: ['content-type', 'authorization']
    # Allow GET, POST, PATCH, DELETE, OPTIONS, etc..
    allowedMethods: ['*']
    # Allow access from a local web server running on port 3000.
    allowedOrigins: ['http://localhost:3000']

Rebuild the cache to rebuild the system, example: drush cr

Configure the site on just your local setup

Edit sites/default/development.services.yml and add the values for CORS. See the example above.

Rebuild the cache to rebuild the system, example: drush cr