Quick Start Guide
https://github.com/acquia/reservoir
https://github.com/acquia/reservoir-project
https://github.com/damontgomery/well (Reservoir, BLT, Drupal VM)
https://github.com/ba66e77/mrpink (Reservoir, BLT, Drupal VM)
https://www.datasmith.net/article/setting-blt-reservoir
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.
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.
/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.
/admin/access/permissions
Roles are not worth much without permissions. Allow the new role to create, delete, etc content.
/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.
When creating a client, you will see scopes based on the roles you created earlier.
/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.
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.
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.
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.
Reservoir will generate documentation for the API for each site. Visit /admin/api
No authentication is required.
Make a GET request to /jsonapi/node/article
You can view the response as JSON.
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.
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)
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"
}
}
}
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.
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
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