To much fanfare, Drupal 8 was released in 2015 with web services capabilities off the shelf. But that doesn’t mean our work finished there; the community, thanks to the hard work of the API-first initiative team, has been actively addressing new changes in the surrounding world of web services. The two intervening minor versions of Drupal 8 since 2015 are chock full of improvements. Even so, the wider web services landscape is rapidly shifting, and new approaches and ideas are quickly gaining momentum in an increasingly diverse landscape. For instance, in the front-end world, particularly in the JavaScript community, emerging specifications such as JSON API and GraphQL are overturning our long-held perceptions about what a web services API is capable of. Key topics covered in this tech talk include: How Drupal’s web services have evolved and progressed since the release of Drupal 8 How the wider landscape of web services has shifted around us How we’re securing Drupal’s place at the vanguard of API-first content management What’s most relevant to you as a decoupled app developer in Drupal 8.1, 8.2, and 8.3

1. ©2016 Acquia Inc. — Confidential and Proprietary
Decoupled Drupal 8.x
Drupal’s web services
today and tomorrow
Preston So
Development Manager, Acquia Labs
March 29, 2017

2. ©2016 Acquia Inc.
Welcome!
Preston So (@prestonso) has been a web developer and designer since
2001, a creative professional since 2004, and a Drupal developer since
2007. As Development Manager of Acquia Labs, Preston leads new
open-source and research initiatives at Acquia. Preston has presented
keynotes at conferences on three continents in multiple languages and
speaks around the world about diverse topics such as decoupled
Drupal, responsive design, front-end development, and user experience.
– drupal.org/u/prestonso
– preston.so@acquia.com

3. ©2016 Acquia Inc.
Welcome!

4. ©2016 Acquia Inc.
What we’ll cover
– Drupal web services at a glance
– Drupal 8.0: WSCII and foundations
– Drupal 8.2: CORS, configuration entities, and DX
– Drupal 8.3: User registration and DX
– What’s ahead in Drupal 8.5+
– JSON API, GraphQL, and RELAXed Web Services
– Epilogue: The wider web services landscape

5. ©2016 Acquia Inc.
Drupal web services at
a glance

6. ©2016 Acquia Inc.
Why are web services important?
– Web services enable communication between Drupal and other
systems, most commonly decoupled front ends or other back ends.
– Decoupled Drupal, or API-first Drupal, is the process of employing
Drupal as a data service which exposes data for consumption by
other applications.
– A REST API is a common entry point for other applications.

7. ©2016 Acquia Inc.
Why are web services important?
HTTP request
HTTP response (JSON, XML)
Site or repository built in
Drupal
Decoupled
application
Web services
Decoupled
application
Software
development
kit (SDK)

8. ©2016 Acquia Inc.
Drupal web services at a glance
– Drupal’s web services can be split into three categories:
–Core REST (internal storage or HAL normalization)
–Contributed REST (JSON API, RELAXed, Services)
–Non-REST web services (GraphQL)

9. ©2016 Acquia Inc.
Drupal web services at a glance

10. ©2016 Acquia Inc.
Drupal 8.0: WSCII and
foundations

11. ©2016 Acquia Inc.
WSCII
– The Web Services and Context Core Initiative (WSCII), led by Larry
Garfield, enabled RESTful web services in Drupal.
– The original goal was to enable server-to-server communication, but
in recent years actual usage has evolved more toward server-to-
client.
– The default REST API available out of the box in Drupal 8 core is
fully REST-compliant.

12. ©2016 Acquia Inc.
The API-first initiative
– The API-first initiative (WSCII), led by Wim Leers, is the successor to
WSCII and aims to expand Drupal’s web services capabilities.
– The API-first initiative captures use cases that are applicable to both
fully decoupled and progressively decoupled (in-Drupal) issues.
– Meetings are held monthly on the third Monday of every month from
6-7pm GMT, and core conversations often take place at DrupalCon.

13. ©2016 Acquia Inc.
Core REST
– The core REST modules allow for all content entities (nodes, users,
taxonomy terms, comments) to be exposed as JSON+HAL or as
JSON representing Drupal’s internal storage, and Views natively
supports “REST export” as a new display type.
– There are many issues with REST in core; please consider
contributing to RX (REST experience) tagged issues.

14. ©2016 Acquia Inc.
Core REST modules
– Serialization is able to perform serialization by providing normalizers
and encoders. First, it normalizes Drupal data (entities and their
fields) into arrays with a particular structure. Any normalization can
then be sent to an encoder, which transforms those arrays into data
formats such as JSON or XML.
– RESTful Web Services allows for HTTP methods to be performed on
existing resources including but not limited to content entities and
views (the latter facilitated through the “REST export" display in
Views) and custom resources added through REST plugins.

15. ©2016 Acquia Inc.
Core REST modules
– HAL builds on top of the Serialization module and adds the
Hypertext Application Language normalization, a format that
enables you to design an API geared toward clients moving
between distinct resources through hyperlinks.
– Basic Auth allows you to include a username and password with
request headers for operations requiring permissions beyond that of
an anonymous user. It should only be used with HTTPS.

16. ©2016 Acquia Inc.
Setting up RESTful Drupal
$ drush en -y hal basic_auth serialization rest
$ drush dl restui && drush en -y restui

17. ©2016 Acquia Inc.
Fetching an individual node
GET /node/1?_format=json HTTP/1.1
Host: drupal-backend.dd:8083
Accept: application/json
Cache-Control: no-cache
Postman-Token: 6c55fb8b-3587-2f36-1bee-2141179d1c9c

18. ©2016 Acquia Inc.
Creating a new node
POST /entity/node HTTP/1.1
Host: drupal-backend.dd:8083
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/json
Cache-Control: no-cache
Postman-Token: 7776d489-e9bb-cad2-d289-24aa76f8f8a6

19. ©2016 Acquia Inc.
Creating a new node
{
"type": [
{"target_id": "article"}
],
"title": [
{"value": "Lorem ipsum dolor sit amet adipiscing"}
],
"body": [
{"value": "This is a totally new article"}
]
}

20. ©2016 Acquia Inc.
Updating an individual node
PATCH /node/23 HTTP/1.1
Host: drupal-backend.dd:8083
Accept: application/json
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/json
Cache-Control: no-cache
Postman-Token: c1e4df7e-b17b-2256-75c8-55629c8329c7

21. ©2016 Acquia Inc.
Updating an individual node
{
"nid": [
{"value": "23"}
],
"type": [
{"target_id": "article"}
],
"title": [
{"value": "UPDATE UPDATE UPDATE UPDATE"}
],
"body": [
{"value": "Awesome update happened here"}
]
}

22. ©2016 Acquia Inc.
Cross-origin resource sharing (CORS)
# Apache 2
Header set Access-Control-Allow-Origin "*"

23. ©2016 Acquia Inc.
Cross-origin resource sharing (CORS)
$ drush dl cors && drush en -y cors
*|http://localhost:3003
$ drush cr

24. ©2016 Acquia Inc.
Waterwheel SDK ecosystem
– Waterwheel is a collection of SDKs which make it easier for
developers to build Drupal-backed applications in various
technologies.
– The Waterwheel module includes resource discovery (content
schema exports to the client side) and generated Swagger API
documentation.
– github.com/acquia/waterwheel.js
– github.com/acquia/waterwheel.swift
– drupal.org/project/waterwheel

25. ©2016 Acquia Inc.
Drupal 8.2: CORS,
configuration entities,
and DX

26. ©2016 Acquia Inc.
Changes in Drupal 8.2
– Configuration entity GET support
– Opt-in CORS support
– RPC endpoints for login, status, logout, and password reset
– REST configuration converted to configuration entities
– Comments can be updated via REST
– Various developer experience benefits

27. ©2016 Acquia Inc.
Configuration entity GET support
– Configuration entities can now be retrieved via GET, meaning you
can now view labels of configuration entities like Vocabularies and
Content Types, which is particularly helpful for client-side visibility.
curl --user admin:admin --request GET
"http://drupal.d8/entity/taxonomy_vocabulary/tags?_format=json"
curl --user admin:admin --request GET
"http://drupal.d8/contact/feedback?_format=json"

28. ©2016 Acquia Inc.
Opt-in CORS support
– Fully decoupled applications on domains distinct from the Drupal
back end are blocked from issuing asynchronous requests to Drupal
due to the same-origin policy unless cross-origin resource sharing is
enabled.
– In the past, this was done either via Apache 2 configuration or via
the CORS module, but there is now core support.
– This is not enabled by default due to security consequences of
allowing other domains to access Drupal.

29. ©2016 Acquia Inc.
Opt-in CORS support: default.services.yml
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

30. ©2016 Acquia Inc.
RPC endpoints for user operations
– You can now log into Drupal, check a user’s status, log out, and
reset a password entirely through RPC endpoints.

31. ©2016 Acquia Inc.
RPC endpoints for login, status, logout, and reset
curl --header "Content-type: application/json" --request POST
--data '{"name":"admin", "pass":"admin"}'
http://drupal.d8/user/login?_format=json
curl --header "Content-type: application/json" --request GET
http://drupal.d8/user/login_status?_format=json
curl --header "Content-type: application/json" --request POST
http://drupal.d8/user/logout?_format=json

32. ©2016 Acquia Inc.
REST configuration before: rest.settings
resources:
entity:node:
GET:
supported_formats:
- hal_json
supported_auth:
- basic_auth
POST:
supported_formats:
- hal_json
supported_auth:
- basic_auth
PATCH:
supported_formats:
- hal_json
supported_auth:
- basic_auth
DELETE:
supported_formats:
- hal_json
supported_auth:
- basic_auth

33. ©2016 Acquia Inc.
REST configuration after: rest.resource.entity.node
id: entity.node
plugin_id: 'entity:node'
granularity: method
configuration:
GET:
supported_formats:
- hal_json
supported_auth:
- basic_auth
POST:
supported_formats:
- hal_json
supported_auth:
- basic_auth
PATCH:
supported_formats:
- hal_json
supported_auth:
- basic_auth
DELETE:
supported_formats:
- hal_json
supported_auth:
- basic_auth
dependencies:
module:
- basic_auth
- hal
- node

34. ©2016 Acquia Inc.
Various developer experience benefits
– Entity creation via REST now returns the created entity in the
response
– Entity update via REST now returns the updated entity in the
response

35. ©2016 Acquia Inc.
Drupal 8.3: User registration and DX
– User registration is now possible through REST
– Various developer experience advancements (changes in module
scope and REST plugin writing process)

36. ©2016 Acquia Inc.
What’s ahead in Drupal
8.5+

37. ©2016 Acquia Inc.
Prospective improvements in Drupal 8.5+
– Translation support
– File upload support
– Configuration entity POST, PATCH, DELETE support?
– Others?

38. ©2016 Acquia Inc.
JSON API, GraphQL,
and RELAXed Web
Services

39. ©2016 Acquia Inc.
RELAXed Web Services
– RELAXed Web Services extends features available in core’s REST modules
by including support for translations, parent revisions (through the
Multiversion module), file attachments, and cross-environment UUID
references.
– It uses the CouchDB API specification, which means that CouchDB
integration with client-side libraries such as PouchDB and Hood.ie makes
possible offline-enabled Drupal.

40. ©2016 Acquia Inc.
JSON API
– JSON API is a specification for REST APIs in JSON popular among
JavaScript developers and adopted by the Ember and Rails
communities.
– JSON API provides a standard way to query single entities, but it
also provides all relationships contained therein and query
operations via query string parameters.
– JSON API allows you to fetch lists of content entities (filter, sort,
pagination) — which is currently only possible via multiple requests
or Views REST exports.

41. ©2016 Acquia Inc.
JSON API
– JSON API is likely slated for incorporation into Drupal 8.5 core,
though this is prospective. The module is very close to entering beta
for stability in contrib.
– See also: JSON API by Mateu Aguiló Bosch
(drupal.org/project/jsonapi)

42. ©2016 Acquia Inc.
OAuth2
– Currently Basic Auth is the only way to authenticate into Drupal’s
REST API, and it is less secure than other available options such as
OAuth2.
– OAuth2 is more secure for authenticating requests, and it is a widely
used standard among REST APIs in the wider landscape.
– See also: Simple OAuth by Mateu Aguiló Bosch
(drupal.org/project/simple_oauth)

43. ©2016 Acquia Inc.
GraphQL
– GraphQL, originally created by Facebook to power its data fetching,
is a query language that enables fewer queries and limits response
bloat.
– Rather than tightly coupling responses with a predefined schema,
GraphQL overturns this common practice by allowing for the client's
request to explicitly tailor a response so that the client only receives
what it needs.
– GraphQL shifts responsibility from the server to the client: the server
publishes its possibilities, and the client publishes its requirements
instead of receiving a response dictated solely by the server.

44. ©2016 Acquia Inc.
GraphQL
– Typical REST APIs tend to be static (or versioned, in many cases, e.g. /api/v1)
in order to facilitate backwards compatibility for applications. However, in
Drupal's case, when the underlying content model is inevitably augmented
or otherwise changed, schema compatibility is no longer guaranteed.
– With GraphQL's native schema introspection and client-specified queries,
the API is much less opaque from the client's perspective in that the client is
aware of what response will result according to its own requirements.
– See also: GraphQL by Sebastian Siemssen (drupal.org/project/graphql)

45. ©2016 Acquia Inc.
Summary: Current core REST

46. ©2016 Acquia Inc.
Summary: JSON API

47. ©2016 Acquia Inc.
Summary: GraphQL

48. ©2016 Acquia Inc.
Epilogue: The wider
web services
landscape

49. ©2016 Acquia Inc.
The GraphQL ecosystem
– GraphQL
– React/Relay
– Apollo Data

50. ©2016 Acquia Inc.
Content as a service
– Contentful
– Prismic
– Built.io Contentstack
– CloudCMS
– Kentico Cloud

51. ©2016 Acquia Inc.
The future of the CMS
– Inversion of control
– Editorial experience
– Developer experience
– User experience

52. ©2016 Acquia Inc.
Thank you!
Preston So (@prestonso)
drupal.org/u/prestonso
preston.so@acquia.com
Learn more about Acquia Labs:
acquia.com/resources/acquia-labs