API-first initiative

Mateu Aguiló Bosch
Drupal.org: e0ipso
@e0ipso
 

Senior Developer
Lullabot logo

Wim Leers
Drupal.org: Wim Leers
@wimleers
wimleers.com

Principal Software Engineer, OCTO
Acquia logo

Quick questionnaire! 📝

  • Who has worked on decoupled Drupal projects?
    • If no, would you like to in the future?
  • Did you use
    • Core's REST module?
    • JSON API or GraphQL?
✍️

Vision

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, OAuth 2.0, etc.)

People want need this!

We talked about this a lot:

  • DrupalCon Baltimore: 12 sessions, 1 training
  • Decoupled Dev Days
  • DrupalCon Nashville: 1 summit and MANY sessions
  • …

Goals

Must have
  • Make D8 REST usable ✅
  • Make D8 REST best-in-class 🏋️🏋️🏋️
  • Excellent docs via OpenAPI 🏋️🏋️🏋️
Should have
  • JSON API ✅
  • GraphQL 🏋️🏋️🏋️🏋️🏋️
  • Workflows: UUID and revision
Could have
  • OAuth 2.0 support ✅
  • CouchDB support 🏋️🏋️

Goals (6 months ago)

Must have
  • Make D8 REST usable ✅
  • Make D8 REST best-in-class 🏋️🏋️
  • Excellent docs via OpenAPI 🏋️🏋️
Should have
  • JSON API ✅
  • GraphQL 🏋️🏋️
  • Workflows: UUID and revision
Could have
  • OAuth 2.0 support 🏋️
  • CouchDB support 🏋️🏋️

Goals (12 months ago)

Must have
  • Make D8 REST usable ✅
  • Make D8 REST best-in-class 🏋️
  • Excellent docs via OpenAPI 🏋️
Should have
  • JSON API 🏋
  • GraphQL
  • Workflows: UUID and revision
Could have
  • OAuth 2.0 support
  • CouchDB support 🏋️

Why?

REST API
  • Multiple formats
  • Non-entity REST resources
  • Very configurable
JSON API → stable 8.3 contrib → mature 8.4–5 contrib → core 8.6
  • Opinionated spec ⇒ better tooling, less bikeshedding
  • Collection support ⇒ custom REST export views
  • Not configurable: any entity that Entity Access allows
GraphQL → stable 8.4–5 contrib
Great for UI components to fetch only necessary data!
Excellent docs via OpenAPI → stable 8.4–5 contrib
Starting is too painful ⇒ docs with interactive examples

Roadmap

Current focus

REST API → best in class
Missing: translations, modifying config, file uploads 🎉.
Much is blocked on subsystems in Drupal 8.
JSON API → mature 8.4–5 contrib → core 8.6
Missing: comprehensive test coverage, plus 🎉 the above.
GraphQL → stable 8.4–5 contrib
Missing: more sites using it, to stabilize 🎉.
Excellent docs via OpenAPI
12 mo ago: competition (rest_api_doc, Schemata, Docson, OpenAPI)
Now: standardizing on OpenAPI!

Team

  • Wim Leers (Coordinator)
    REST + Serialization + JSON API
  • e0ipso(Coordinator)
    JSON API + OAuth 2.0 + Subrequests + Consumers + Decoupled Router + …
  • gabesullice JSON API
  • tedbow OpenAPI + REST + Serialization + jsdrupal
  • richgerdes OpenAPI
  • pmelab GraphQL
  • dawehner jsdrupal + REST + Serialization + JSON API
  • …
Help wanted 😸

Ecosystem

Tooling

github.com/acquia/waterwheel.js
github.com/acquia/waterwheel.swift

Others!
https://github.com/gabesullice/juissy

Distributions

contentacms.org
Productivity boost for Decoupled Drupalists

Outstanding challenges

Content Staging
previews of decoupled consumers
Improve DX further
entity validation error responses, field aliasing …
Dogfooding
let Drupal consume HTTP APIs (🤝 JS Initiative)
API versioning
😱
…

Open discussion

You are too quiet…

How much of this should we have in Drupal core?

What are the best places to start dogfooding this?

What features are you excited about? Why?

What authentication providers should we add?

Do we support decoupled admin interfaces?