With the inclusion of JSON:API in Drupal core, we now have a solid, stable path to support decoupled Drupal through standardization of payload structures and query string parameters. This session will cover: Why JSON:API instead of the REST module, GraphQL, Relaxed WS, etc. JSON:API overview Authentication with JSON Web Tokens Requests, filters, sorting, pagination File uploads Gotchas

1. 222 Third Street, Suite 234 Cambridge, MA 02142 | www.bioraft.com
JSON:API 2
A Path To Decoupled Drupal

2. Senior Drupal Developer at
BioRAFT
Drupal:
https://www.drupal.org/u/ebeyrent
Twitter:
https://twitter.com/ebeyrent
LinkedIn:
https://www.linkedin.com/in/
erichbeyrent
ERICH BEYRENT

3. Agenda
• What is JSON:API

4. Agenda
• What is JSON:API
• Why JSON:API?

5. Agenda
• What is JSON:API
• Why JSON:API?
• JSON:API overview

6. Agenda
• What is JSON:API
• Why JSON:API?
• JSON:API overview
• Authentication with JSON Web Tokens

7. Agenda
• What is JSON:API
• Why JSON:API?
• JSON:API overview
• Authentication with JSON Web Tokens
• Requests, filters, sorting, pagination

8. Agenda
• What is JSON:API
• Why JSON:API?
• JSON:API overview
• Authentication with JSON Web Tokens
• Requests, filters, sorting, pagination
• File uploads, image derivatives

9. Agenda
• What is JSON:API
• Why JSON:API?
• JSON:API overview
• Authentication with JSON Web Tokens
• Requests, filters, sorting, pagination
• File uploads, image derivatives
• Gotchas

10. { JSON:API }
A Specification For Building APIs In JSON

11. { json:api }
• It’s a specification that Drupal now implements
• Designed to be readable, flexible, and
discoverable
• Design to minimize the number of requests
and amount of data transmitted
• Provides a new IANA-registered media type
application/vnd.api+json

12. Why JSON:API?
• High Productivity
• Minimum requests to the server
• Efficient use of caching
• Great filtering, pagination, and sorting
• Related resources in one request
• Supports sparse field sets

13. Why not core REST?
• Multiple requests are needed for common needs*
• Responses are bloated
• Doesn’t follow widely accepted guidelines or
specifications
• Data structures are not consistent
• Doesn’t support sparse fieldsets*
• No support for bulk writing of data
• Configuration requires a contrib module (REST UI)
• No support for decoupled filtering

14. Why not core GraphQL?
• Often requires extra infrastructure
• Clients often require additional libraries
• Extra work to be able to use CDNs and browser caches
• Each implementation dictates how writes are handled; there is
no standard
• GraphQL queries can get very large making GET requests
impossible to cache
• Servers require their own tooling to support the full benefit of
GraphQL
• May require additional permissions, configuration, and custom
code

15. JSON:API Overview
• Defaults to Read-Only mode
• admin/config/services/jsonapi

16. JSON:API Overview
• Enable Counts
• admin/config/services/jsonapi/extras

17. JSON:API Overview
• Headers
The follow headers are required on all GET request to get a
proper JSON:API request and response.
✦ Accept: application/vnd.api+json
✦ Content-Type: application/vnd.api+json

18. JSON:API Overview
• Response Document
Structure
{
jsonapi: {
},
data: {
},
included: {
}
meta: {
},
links: {
}

19. JSON:API Overview
• Response Document
Structure
{
jsonapi: {
},
data: {
},
included: {
}
meta: {
},
links: {
}
Contains the jsonapi
version and link to
the jsonapi schema

20. JSON:API Overview
• Response Document
Structure
{
jsonapi: {
},
data: {
},
included: {
}
meta: {
},
links: {
}
Contains “resource objects” - a
JSON representation of a single
entity
{

21. JSON:API Overview
• Response Document
Structure
{
jsonapi: {
},
data: {
},
included: {
}
meta: {
},
links: {
}
JSON:API Extras adds this,
contains a count of all resource
objects matched by the query

22. JSON:API Overview
• Response Document
Structure
{
jsonapi: {
},
data: {
},
included: {
}
meta: {
},
links: {
}
Contains a link to the query
executed

23. Includes
• Allows you to get all related data in one
request
• Related entities shared by resource objects are
fetched only once
• Each relationship has an id that correlates to a
matching id in the includes

24. Basic Authentication
• Enable the HTTP Basic Authentication module
Authorization: Basic <Base64EncodedUser/Password>

25. Authentication with JWT
• Install the Key and JWT modules*
• Signing and validating JWTs requires a secret
• JWT HMAC
head -c 64 /dev/urandom | base64 -w 0 > /path/to/private/dir/jwt.key.txt
• JWT RSA Key
openssl genrsa -out private.key 2048 > /path/to/private/dir/jwt.key.txt
• The Key module provides the storage for
these keys, which JWT uses

26. Authentication with JWT
• The secret is shared between client and server
• The client encodes a JWT using the shared
secret
• The JWT is passed in as a Bearer token
• The JWT module decodes the Bearer token and
uses the uid property to create a Drupal
session for that user

27. Authentication with JWT
• Payload
{
'iss': 'mydomain.com',
'iat': 1516239022,
'exp': 1562762688,
'drupal': {
'uid': 45
}
}
Authorization: Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZ
SI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJkcnVwYWwiOnsidWlkIjo0NX
19.w2NqGAQXLYn5iBOkG9NM1ImTtVBDKoi76RDGFMZomm8

28. Collections
• Queries are resource-based
• /jsonapi/node
• /jsonapi/node/article
• /jsonapi/node/article/10eb67d4-
c045-4b9b-9e2b-5ea299122a67
Which of these is wrong?

29. Requests, filters, sorting, pagination
• GET
• POST
• PATCH
• DELETE

30. File uploads, image derivatives
• File uploads are a two-step process
• POST the file, get the response
• Attach the file entity to another entity using
the id in the response

31. Image derivatives
• Enable the Consumer and Consumer Image
Styles modules
• Configure
• Add the consumer id to your request headers
X-Consumer-ID: {{ your_consumer_id }}

32. Gotchas
• JSON:API is entirely resource-based, you can’t get a result set
with different resources
• Doesn’t support business logic (reset passwords, registering
users)
• Resource limits are capped at 50 per request
• Limited multilingual functionality
• Some filters may be too much for GET; custom code will be
needed to transform POST (use a route enhancer)
• Some queries with includes will result in very large responses,
may have to make multiple requests in parallel

33. Resources
• https://jsonapi.org
• https://drupal.org/project/jsonapi
• https://drupal.org/docs/8/modules/jsonapi
• https://dri.es/headless-cms-rest-vs-jsonapi-vs-
graphql