API-first initiative

Mateu Aguiló Bosch
Drupal.org: e0ipso
@e0ipso
 

Senior Developer
Lullabot logo

No Mateu today 😥

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

Principal Software Engineer, OCTO
Acquia logo

What we'll cover

  • Vision
  • Goals
  • Roadmap
  • Ecosystem
  • Outstanding challenges
  • Open discussion

Quick questionnaire! 📝

  • Who has worked on decoupled Drupal projects?
    • If yes,
      • >1 year ago? >6 months ago? <6 months ago/now?
      • was it critical to the overall project?
    • If no, would you like to in the future?
  • Did you use
    • Core's REST module? and the contrib REST UI module?
      • Did it noticeably improve in the past year?
    • JSON API?
    • GraphQL?
    • A combination?
✍️

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, Basic Auth, OAuth2)

People want need this!

We talked about this a lot:

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
  • CouchDB support
  • OAuth2 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
  • CouchDB support
  • OAuth2 support

Why?

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

Roadmap

Team

Wim Leers
Initiative coordinator (esp. REST + Serialization + JSON API)
e0ipso
JSON API coordinator + OAuth2
dawehner
REST + Serialization + JSON API
tedbow
OpenAPI coordinator + REST + Serialization
damiankloip
Serialization maintainer + REST

Roadmap

  • Core REST: mature further
  • JSON API: mature further, prepare for core inclusion
  • GraphQL: stable contrib release

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 contrib → core 8.5
Missing: comprehensive test coverage, plus the above.
GraphQL → stable 8.4 contrib
Missing: sites using it, to stabilize.
Excellent docs via OpenAPI
6 mo ago: competition (rest_api_doc, Schemata, Docson, OpenAPI)
Now: standardizing on OpenAPI!

Next

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.
Help wanted 😹

Acquia logo is hiring — talk to me!

Ecosystem

Tooling

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

Distributions

Contenta — contentacms.org
Productivity boost for Decoupled Drupalists
(Keeps Drupalisms + provides example apps!)
Reservoir — github.com/acquia/reservoir
Empower non-Drupalists
(Simplicity first: only 7 concepts!)

Outstanding challenges

Image styles
for responsive images
Improve DX further
entity validation error responses, field aliasing …
Dogfooding
let Drupal core functionality consume HTTP APIs
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?