Secrets of the decoupled Drupal practitioner Preston So April - - PowerPoint PPT Presentation

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. preston@gatsbyjs.com • @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 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.

Call for papers The Decoupled Days 2019 call for papers is extended until May 3, 2019 at 11:59pm EST. Sponsorships For sponsorship information, reach out to our team at decoupleddays@gmail.com. @decoupleddays Follow 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 reintroduction to decoupled Drupal

1

Decoupled 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 application HTTP 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 JSON

Web 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

• thers 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 E-mail 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 of Drupal as a content service for consumer applications

An alternative API: RELAXed Web Services

2

Decoupled 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 on REST 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-0 123-43a6-a71e-914d9432ab 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

Extending JSON:API with

Extras and Defaults

3

Decoupled 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

• ught 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

4

Decoupled 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 lightweight protocol 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

5

Decoupled 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

• rmat}&_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

6

Decoupled 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 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. preston@gatsbyjs.com • @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 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.

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