Secrets of the

decoupled Drupal practitioner

Preston So • April 11, 2019 • DrupalCon Seattle 2019

Welcome!

Preston is a product strategist, innovation lead, developer advocate,

speaker, and author of Decoupled Drupal in Practice (Apress, 2018).

A globally recognized voice on decoupled Drupal and subject matter

expert in the decentralized web and conversational design, Preston is
Principal Product Manager at Gatsby, where he works on improving
the Gatsby developer experience and driving product development.

Having spoken at over 50 conferences, Preston is a sought-after

presenter with keynotes on five continents and in three languages.

[email protected] • @prestonso • #decoupleddrupalsecrets

Gatsby

Gatsby’s ecosystem
✋
Come say Hi!
@gatsbyjs
Meet me and members of the
github.com/gatsbyjs/gatsby Gatsby team at booth #319!
www.gatsbyjs.org
 Decoupled Drupal in Practice
Pre-order now:
tiny.cc/decoupled-in-practice

In the first and only comprehensive guide to

decoupled Drupal across the stack, with a foreword
by Drupal project lead Dries Buytaert, learn
everything you need to know about decoupled
Drupal—from building the back end and designing
APIs to integrating with front-end technologies.

4
Call for papers Sponsorships @decoupleddays
The Decoupled Days 2019 call For sponsorship information, Follow us on Twitter to stay
for papers is extended until reach out to our team at updated on important
May 3, 2019 at 11:59pm EST. [email protected]. announcements.

#decoupleddays • decoupleddays.com • @decoupleddays

What we'll cover

● A brisk reintroduction to decoupled Drupal

● An alternative API: RELAXed Web Services
● Extending JSON:API with Extras and Defaults
● Running Drupal remotely: JSON-RPC
● Derived schemas and docs: Schemata and OpenAPI
● Rev up with reverse proxies: Contenta.js
● Epilogue: What to expect in decoupled Drupal in the 8.7
era
Psst … secrets ahead!
 Decoupled Drupal in Practice
Chapter 4

1 A brisk reintroduction
to decoupled Drupal
 Drupal front end

Client Client

Server Server

Drupal

Monolithic Drupal
 HTTP request

Decoupled
Web service HTTP client
HTTP response application

Site or repository built in Decoupled

Drupal application
 HTML HTML

Other
language Decoupled application
Drupal front end

Templates Templates
PHP

Web service
JSON
Drupal
PHP
Drupal
Data Data

Monolithic vs. decoupled Drupal

 JavaScript application
framework
JavaScript framework
(client-side execution)
Initial markup
Client Client

Server Server
JavaScript framework
(server-side
Drupal
execution)

Node.js

Drupal
Server-side JavaScript
 Synchronous Lorem ipsum Subscribe
dolor sit
Asynchronous
amet, E-mail
consectetuer
adipiscing. Submit
JavaScript framework
(client-side execution) HTTP
request Lorem ipsum
Subscribe to our newsletter
dolor sit
Client E-mail address
amet,
consectetuer
Server adipiscing. Submit
JavaScript framework
(server-side
execution)
Lorem ipsum Success!
Node.js dolor sit Here are
HTTP amet, others that
request
consectetuer might interest
adipiscing. you:
Drupal

Dynamic pages with server-side prerendering

 Server Client

responds

Node.js

executes

JavaScript framework

renders
flush
HTML HTML

bindings by

JavaScript framework

calls REST API

Synchronous

Universal (isomorphic) JavaScript Asynchronous

 Server Client

Node.js
calls
responds REST executes
API

Drupal JavaScript framework

responds
renders
flush
HTML HTML

bindings by

JavaScript framework

calls REST API

Synchronous

Universal JavaScript consuming Drupal Asynchronous

Risks and rewards

Area Rewards Risks

Architecture Separation of Loss of contextual

concerns administration

Development Pipelined Maintainability

experience development difficulties

Security and Administrative Additional point of

performance security failure

Project management Easier resourcing On-boarding overhead

Decoupled Drupal is the use of
Drupal as a content service for
consumer applications
 Decoupled Drupal in Practice
Chapters 8 and 13

2 An alternative API:
RELAXed Web Services
RELAXed Web Services

● RELAXed Web Services (maintained by timmillwood and

jeqq) implements the Apache CouchDB specification
and emphasizes content staging use cases as part of
the Drupal Deploy ecosystem.

● CouchDB stores data within JSON documents

(resources) exposed through a RESTful API.

● Unlike Drupal’s core REST API, CouchDB allows not only

GET, POST, and DELETE but also PUT and COPY.

https://www.drupal.org/project/relaxed
 Drupal core Depends on
(with HAL normalization) REST and Serialization

HAL RELAXed Web Services

REST Waterwheel

depends on
Depends on Serialization

Serialization JSON API

Drupal core
(raw JSON structures, no HAL) GraphQL

Drupal's web services ecosystem (not exhaustive)

 REST APIs

RELAXed Web
Core REST JSON API GraphQL
Services

REST APIs

Web services

Euler diagram of Drupal web services

A note about code examples

HTML

JavaScript (ES5, ES6)

JSON

Command line
Installing RELAXed

# Use Composer to install RELAXed Web Services and

# its dependency relaxedws/replicator.
$ composer require relaxedws/replicator:dev-master
$ composer require drupal/relaxed
$ drush en -y relaxed
RELAXed Web Services configuration, including Replicator user
RELAXed Web Services

● RELAXed Web Services doesn’t require you to use its

content staging capabilities (but you will need to
configure the Replicator user and install Workspaces if
so).

● Without Workspaces enabled, the default workspace

accessible in RELAXed Web Services is live.
Testing RELAXed Web Services

GET /relaxed → 200 OK

{
"couchdb": "Welcome",
"uuid": "02286a1b231b68d89624d281cdfc0404",
"vendor": {
"name": "Drupal",
"version": "8.5.6",
},
"version": "8.5.6"
}
Retrieving with RELAXed

URI Description Example

GET /relaxed/_all_dbs Retrieve all workspaces /relaxed/_all_dbs

GET Retrieve a single /relaxed/live

/relaxed/{workspace} workspace /relaxed/stage

GET Retrieve all document /relaxed/live/_all_docs

/relaxed/{workspace}/_ identifiers (entity ids) in a
all_docs workspace

GET Retrieve a single /relaxed/live/462e86f6-0

/relaxed/{workspace}/{ document (Drupal entity) 123-43a6-a71e-914d9432ab
document_id} 6e
Sample RELAXed response for a single Drupal entity
Creating documents (entities)

POST /relaxed/live → 201 Created

{
"@context": {
"_id": "@id",
"@language": "en"
},
"@type": "node",
"_id": "b6cea743-ba86-49b0-81ac-03ec728f91c4",
"en": {
"@context": {
"@language": "en"
},
"langcode": [{ "value": "en" }],
"type": [{ "target_id": "article" }],
"title": [{ "value": "REST and RELAXation" }],
Creating documents (entities)

POST /relaxed/live → 201 Created

"body": [
{
"value": "This article brought to you by a request to RELAXed Web
Services!"
}
]
}
}
RELAXed Web Services
is a powerful RESTful alternative
 Decoupled Drupal in Practice
Chapter 23

3 Extending JSON:API with

Extras and Defaults
JSON:API Extras

● Sometimes, we need to override the defaults that are

preconfigured upon installing the JSON:API module.

● JSON:API Extras provides interfaces to override default

settings and establish new ones that the resultant API
ought to follow, including:

○ enabling/disabling individual resources

○ aliasing resource names and paths
○ disabling individual fields in entities
○ aliasing field names
○ modifying field output through field enhancers
Installing both modules

# Install JSON:API Extras.

$ composer require drupal/jsonapi_extras
$ drush en -y jsonapi_extras

# Install JSON:API Defaults.

$ drush en -y jsonapi_extras jsonapi_defaults
Configuring JSON:API Extras
Configuring JSON:API Extras
JSON:API Defaults

● Formerly a separate module maintained by Martin Kolar

(mkolar), JSON:API Defaults allows you to set default
includes and filters for resources.

● JSON:API Defaults is particularly useful when consumers

prefer issuing slimmer requests without the parameters
required to yield a response including relationships.

● In other words, you can issue a request without params

and receive a response having predetermined defaults
such as includes.
 Decoupled Drupal in Practice
Chapter 23

4 Running Drupal remotely:

JSON-RPC
Justifying JSON-RPC

● Sometimes, deeper functionality in Drupal needs to be

made available to consumers, particularly actions like
performing a cache rebuild or running a cron job.

● RPCs are remote procedure calls that execute a

procedure on another system, written as if they were
local actions, without direct coding.

● RPCs in Drupal would be useful for any action not

representable through REST.
JSON-RPC provides a lightweight
protocol for remote procedure calls
JSON-RPC

● Maintained by Mateu Aguiló Bosch (e0ipso) and Gabe

Sullice (gabesullice), JSON-RPC’s mission is to serve as a
canonical foundation for Drupal administrative actions
relying on more than just REST.

● JSON-RPC also exposes certain internals of Drupal,

including permissions and the list of enabled modules.

https://www.drupal.org/project/jsonrpc
Installing JSON-RPC

$ composer require drupal/jsonrpc

$ drush en -y jsonrpc jsonrpc_core jsonrpc_discovery
Rebuild the cache registry

POST /jsonrpc → 204 No Content

{
"jsonrpc": "2.0",
"method": "cache.rebuild",
}
Retrieve a user’s permissions

POST /jsonrpc → 200 OK

{
"jsonrpc": "2.0",
"method": "user_permissions.list",
"params": {
"page": {
"limit": 5,
"offset": 0
}
},
"id": 2
}
Other common methods

Method Description Parameters

maintenance_mode.isEna Enables or disables enabled

bled maintenance mode

user_permissions.add_p Add the given permission permission, role

ermission_to_role to the specified role

plugins.list List defined plugins page (limit, offset),

service

route_builder.rebuild Rebuilds application’s None

router (result TRUE if
success)
 Decoupled Drupal in Practice
Chapter 24

5 Derived schemas and docs:

Schemata and OpenAPI
Schemata

● Schemas are declarative descriptions outlining the

shape of a JSON document, such as a typical entity
response from a Drupal web service.

● In Drupal 8, the Schemata module, maintained by

Adam Ross (Grayside), is responsible for providing
schemas that facilitate generated documentation and
generated code.

https://www.drupal.org/project/schemata
Installing Schemata

$ composer require drupal/schemata

$ drush en -y schemata schemata_json_schema
Navigating a schema

You can use the browser or GET requests.

● Format:
/schemata/{entity_type}/{bundle}?_format={output_f
ormat}&_describes={described_format}

● /schemata/node/article?_format=schema_json&describ
es=api_json

● /schemata/user?_format=schema_json&describes=hal_j
son
Sample Schemata response for articles
OpenAPI

● OpenAPI (formerly known as the Swagger specification)

describes RESTful web services based on a schema.

● The OpenAPI module, maintained by Rich Gerdes

(richgerdes) and Ted Bowman (tedbow), integrates with
both core REST and JSON:API to document available
entity routes in those web services.

https://www.drupal.org/project/openapi
Installing OpenAPI

# Use ReDoc.
$ composer require drupal/openapi
$ composer require drupal/openapi_ui_redoc
$ drush en -y openapi openapi_ui_redoc

# Use Swagger UI.

$ composer require drupal/openapi
$ composer require drupal/openapi_ui_swagger
$ drush en -y openapi openapi_ui_swagger
 Decoupled Drupal in Practice
Chapter 16

6 Rev up with proxies:

Contenta.js
Contenta.js

● Contenta.js addresses the pressing need for a Node.js

proxy that acts as middleware between a Drupal
content API layer and a JavaScript application.

● A Node.js proxy is useful for decoupled Drupal due to

data aggregation, server-side rendering, and caching.

https://github.com/contentacms/contentajs
Contenta CMS and Contenta.js

● Contenta.js integrates seamlessly with any Contenta

CMS installation that exposes APIs as long as the URI of
the site is provided in configuration.

● Contenta installations with JSON:API, JSON-RPC,

Subrequests, and OpenAPI enabled need no further
configuration.

● Contenta.js contains a multithreaded Node.js server, a

Subrequests server facilitating request aggregation, a
Redis integration, and a friendlier approach to CORS.
7 Epilogue:
What to expect in decoupled
Drupal in the 8.7 era
Decoupled Drupal is no longer
theoretical; it is now reality
Decoupled Drupal’s ecosystem
is robust and rapidly expanding
Final notes

Join us for #DrupalContribution opportunities on Friday, April 12th!

● Mentored Contribution
○ 9:00-18:00, Room 602
● First-Time Contributor Workshop
○ 9:00-12:00, Room 606
● General Contribution
○ 9:00-18:00, Room 6A

What did you think of this session? Locate this session on the
DrupalCon website: https://events.drupal.org/seattle2019/schedule
Thank you!

Preston is a product strategist, innovation lead, developer advocate,

speaker, and author of Decoupled Drupal in Practice (Apress, 2018).

A globally recognized voice on decoupled Drupal and subject matter

expert in the decentralized web and conversational design, Preston is
Principal Product Manager at Gatsby, where he works on improving
the Gatsby developer experience and driving product development.

Having spoken at over 50 conferences, Preston is a sought-after

presenter with keynotes on five continents and in three languages.

[email protected] • @prestonso • #decoupleddrupalsecrets

Gatsby

Gatsby’s ecosystem
✋
Come say Hi!
@gatsbyjs
Meet me and members of the
github.com/gatsbyjs/gatsby Gatsby team at booth #319!
www.gatsbyjs.org
 Decoupled Drupal in Practice
Pre-order now:
tiny.cc/decoupled-in-practice

In the first and only comprehensive guide to

decoupled Drupal across the stack, with a foreword
by Drupal project lead Dries Buytaert, learn
everything you need to know about decoupled
Drupal—from building the back end and designing
APIs to integrating with front-end technologies.

64
Call for papers Sponsorships @decoupleddays
The Decoupled Days 2019 call For sponsorship information, Follow us on Twitter to stay
for papers is extended until reach out to our team at updated on important
May 3, 2019 at 11:59pm EST. [email protected]. announcements.

#decoupleddays • decoupleddays.com • @decoupleddays