Secrets of thedecoupled 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!
Meet me and members of the Gatsby team at booth #319!
@gatsbyjs
github.com/gatsbyjs/gatsby
www.gatsbyjs.org
4
Decoupled Drupal in PracticePre-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.
Call for papersThe Decoupled Days 2019 call for papers is extended until May 3, 2019 at 11:59pm EST.
SponsorshipsFor sponsorship information, reach out to our team at [email protected].
@decoupleddaysFollow us on Twitter to stay updated on important 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!
A brisk reintroductionto decoupled Drupal
1Decoupled Drupal in Practice
Chapter 4
Monolithic Drupal
Drupal
Drupal front end
Client
Server
Client
Server
Site or repository built in Drupal
Decoupled application
Web service Decoupled applicationHTTP client
HTTP request
HTTP response
Monolithic vs. decoupled Drupal
Drupal
Drupal front end
PHP
Data
Templates
HTML
Drupal
Decoupled application
PHP
Data
Templates
HTML
Other language
JSONWeb service
Drupal
JavaScript application framework
Initial markup
Server-side JavaScript
Client
Server
Client
Server
JavaScript framework(client-side execution)
Node.js
JavaScript framework (server-side execution)
Drupal
JavaScript framework(client-side execution)
Node.js
JavaScript framework (server-side execution)
Drupal
Success! Here are others that might interest you:
Lorem ipsum dolor sit amet, consectetuer adipiscing.
Subscribe to our newsletter
E-mail address
Submit
Lorem ipsum dolor sit amet, consectetuer adipiscing.
Subscribe
Submit
Lorem ipsum dolor sit amet, consectetuer adipiscing.
Dynamic pages with server-side prerendering
Client
Server
Synchronous
Asynchronous
HTTP request
HTTP request
Universal (isomorphic) JavaScript
Server Client
Node.js
JavaScript framework
HTML
JavaScript framework
HTML
Synchronous
Asynchronous
executes
renders
flush
bindings by
responds
calls REST API
Universal JavaScript consuming Drupal
Server Client
Node.js
JavaScript framework
HTML
JavaScript framework
HTML
Synchronous
Asynchronous
executes
renders
flush
bindings by
responds
calls REST API
Drupal
calls REST
API
responds
Risks and rewards
Area Rewards Risks
Architecture Separation of concerns
Loss of contextual administration
Development experience
Pipelined development
Maintainability difficulties
Security and performance
Administrative security
Additional point of failure
Project management Easier resourcing On-boarding overhead
Decoupled Drupal is the use ofDrupal as a content service for consumer applications
An alternative API:RELAXed Web Services
2Decoupled Drupal in Practice
Chapters 8 and 13
● 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.
RELAXed Web Services
https://www.drupal.org/project/relaxed
Drupal core(with HAL normalization)
Depends on Serialization
Depends onREST and Serialization
Drupal core(raw JSON structures, no HAL)
REST
Serialization
HAL
JSON API
Waterwheel
RELAXed Web Services
GraphQL
depends on
Drupal's web services ecosystem (not exhaustive)
REST APIs
Web services
REST APIs
Core REST JSON API RELAXed Web Services GraphQL
Euler diagram of Drupal web services
A note about code examples
HTML
JavaScript (ES5, ES6)
Command line
JSON
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 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.
RELAXed Web Services
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 /relaxed/{workspace}
Retrieve a single workspace
/relaxed/live
/relaxed/stage
GET /relaxed/{workspace}/_
all_docs
Retrieve all document identifiers (entity ids) in a workspace
/relaxed/live/_all_docs
GET /relaxed/{workspace}/{
document_id}
Retrieve a single document (Drupal entity)
/relaxed/live/462e86f6-0123-43a6-a71e-914d9432ab6e
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 Servicesis a powerful RESTful alternative
Extending JSON:API withExtras and Defaults
3Decoupled Drupal in Practice
Chapter 23
● 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
JSON:API Extras
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
● 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.
JSON:API Defaults
Running Drupal remotely:JSON-RPC
4Decoupled Drupal in Practice
Chapter 23
● 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.
Justifying JSON-RPC
JSON-RPC provides a lightweightprotocol for remote procedure calls
● 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.
JSON-RPC
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
bled
Enables or disables maintenance mode
enabled
user_permissions.add_p
ermission_to_role
Add the given permission to the specified role
permission, role
plugins.list List defined plugins page (limit, offset),
service
route_builder.rebuild Rebuilds application’s router (result TRUE if success)
None
Derived schemas and docs:Schemata and OpenAPI
5Decoupled Drupal in Practice
Chapter 24
● 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.
Schemata
https://www.drupal.org/project/schemata
Installing Schemata
$ composer require drupal/schemata
$ drush en -y schemata schemata_json_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
Navigating a schema
Sample Schemata response for articles
● 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.
OpenAPI
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
Rev up with proxies:Contenta.js
6Decoupled Drupal in Practice
Chapter 16
● 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.
Contenta.js
https://github.com/contentacms/contentajs
● 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.
Contenta CMS and Contenta.js
Epilogue:What to expect in decoupled Drupal in the 8.7 era
7
Decoupled Drupal is no longertheoretical; it is now reality
Decoupled Drupal’s ecosystemis 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!
Meet me and members of the Gatsby team at booth #319!
@gatsbyjs
github.com/gatsbyjs/gatsby
www.gatsbyjs.org
64
Decoupled Drupal in PracticePre-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.
Call for papersThe Decoupled Days 2019 call for papers is extended until May 3, 2019 at 11:59pm EST.
SponsorshipsFor sponsorship information, reach out to our team at [email protected].
@decoupleddaysFollow us on Twitter to stay updated on important announcements.
#decoupleddays • decoupleddays.com • @decoupleddays