decoupled Drupal practitioner Secrets of the of the decoupled Drupal...everything you need to know...

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


Subscribe

E-mail

Submit


Dynamic pages with server-side prerendering

Client

Server

Synchronous

Asynchronous

HTTP request

HTTP request

Universal (isomorphic) JavaScript

Server Client

Node.js

JavaScript framework

HTML


HTML

Synchronous

Asynchronous

executes

renders

flush

bindings by

responds

calls REST API

Universal JavaScript consuming Drupal

Server Client

Node.js


HTML


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


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


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.


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


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

● 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


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


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


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

decoupled Drupal practitioner Secrets of the of the decoupled Drupal...everything you need to know...

Documents

Transcript of decoupled Drupal practitioner Secrets of the of the decoupled Drupal...everything you need to know...