API-first initiative

Mateu Aguiló Bosch
Drupal.org: e0ipso

Senior Developer
Lullabot logo

Wim Leers
Drupal.org: Wim Leers

Principal Software Engineer, OCTO
Acquia logo

What we'll cover

  • Vision & goals
  • Roadmap and background
  • Outstanding challenges
  • Epilogue: Dogfooding API-first
  • Open discussion

Vision & goals

I believe that it is important to have first-class web services in Drupal out of the box in order to enable top-notch APIs and continue our evolution to become API-first.
— Dries Buytaert

An unparallelled API-first platform

All data available:

  • RESTfully
    • in any format (JSON, HAL+JSON …)
    • in multiple flavors ("HTTP purist", jsonapi.org …)
  • non-RESTfully
    • via GraphQL
    • via CouchDB protocol, for replication & syncing

… using any authentication mechanism (Cookie, Basic Auth, OAuth2)


Must have
  • Make D8 REST usable
  • Make D8 REST best-in-class 🏋️
  • Excellent documentation 🏋️
Should have
  • JSON API 🏋
  • UUID and revision
  • GraphQL
Could have
  • CouchDB support
  • OAuth2 support


  • Multiple formats
  • Non-entity REST resources
  • Very configurable
JSON API → stable in 8.3 contrib → core
  • Opinionated spec ⇒ better tooling, less bikeshedding
  • Collection support ⇒ custom REST export views
  • Not configurable: any entity that Entity Access allows
GraphQL → stable in contrib
Great for UI components to fetch only necessary data!
Excellent documentation → stable in contrib
Starting is too painful ⇒ docs with interactive examples
REST API → best in class
Missing: translations, modifying config, file uploads.
Much is blocked on subsystems in Drupal 8.
JSON API → stable in 8.3 contrib → core
Missing: comprehensive test coverage, plus the above.
GraphQL → stable in contrib
Missing: active development.
Excellent documentation
Missing: active development, standardization.
Currently: rest_api_doc, Schemata, Docson, OpenAPI.


Short term or long term? Depends on contributions!

UUIDs + revisions
“Entity” + REST: no revisions, uses IDs
→ RELAXed Web Services.
OAuth 2
JS & native app developers expect OAuth 2.
CouchDB support
Content replicability for deployment/offline-first
→ RELAXed Web Services.

People want need this!

We talked about this topic a lot this year.


Coding and Development

Core Conversations

Drupal Showcase

Front End


12 sessions and 1 training!

Roadmap & background


Wim Leers
Initiative coordinator, REST subcoord, JSON API
JSON API subcoordinator, OAuth2, Docson
JSON API collaborator, REST collaborator
REST collaborator, OpenAPI collaborator
Serialization maintainer, REST collaborator
  • Core REST: further maturation
  • JSON API: stable 🎉 RIGHT NOW 🎉


Outstanding challenges

Image styles
for responsive images
Stay up-to-date
for high adaptability to the interconnected ecosystem
Improve DX further
Entity validation error responses, field aliasing …
Path alias-based routing

Open discussion

You are too quiet…

How much of this should we have in Drupal core?

What are the best places to start using this internally?

What features are you excited about? Why?

What authentication providers should we add?

Do we support decoupled admin interfaces?

DrupalCon Baltimore 2017


Locate this session at the
DrupalCon Baltimore website:

Take the survey!