REST in Peace

REST in PeaceAPI DEVELOPMENT IN DRUPAL

Kate Marshalkina

Konstantin Komelin

Drupal Consultant from Moscow who fell in love with Drupal in 2011. Interested in i18n, distributions and Drupal 8.Path Breadcrumbs co-maintainer.@kalabro

Drupal Consultant from Saint PetersburgCo-founder of local Drupal CommunityDrupal Trainer at MorningCurve@kkomelin

Let’s REST

Headless?!

What is API for?

Mobile Apps

API

Microservices

API

Frontend Apps

API

What is REST?

ResourceRepresentation

GET /items

POST /items

GET /items/1

PUT /items/1

DELETE /items/1

Methods

REpresentational State Transfer

RESTful or RESTless

REST in Drupal

Services RestWS RESTful Endpoint Drupal 8

Popularity

Documentation

Extensibility

Authentication

Performance

Auto API Docs

Versioning

Serviceshttps://www.drupal.org/project/services

“A standardized solution of integrating external applications with Drupal.”

37,085 sites use this module.

Popularity: ★★★★★

RESTful Web Serviceshttps://www.drupal.org/project/restws

“Builds upon the Entity API, to provide support for all entity types out of the box.”

4,746 sites use this module.

Popularity: ★★★

RESTfulhttps://www.drupal.org/project/restfulhttps://github.com/RESTful-Drupal/restful

“This module allows Drupal to be operated via RESTful HTTP requests, using best practices for security, performance, and usability.”

“Audience is developers and not site builders.”

395 sites use this module.

Popularity: ★★

Endpointhttps://www.drupal.org/project/endpoint

“Endpoint is really light, fast and flexible, that makes it a good solution for projects where Drupal role is mobile backend and single-page app backend.”

7 sites use this module.

Popularity: ★

REST-focused alternative to High-performance JavaScript callback handlerhttps://www.drupal.org/project/js

Drupal 8 RESTCore + https://www.drupal.org/project/restui

“In Drupal 8 core, interactions with content entities are supported via a REST interface. The REST module is extensible, and modules that wish to offer other services can implement Resource Plugins.”

Popularity: ★★

Services RestWS RESTful Endpoint Drupal 8

Popularity

Documentation

Extensibility

Authentication

Performance

Auto API Docs

Versioning

Services RestWS RESTful Endpoint Drupal 8

Popularity

Documentation

Extensibility

Authentication

Performance

Auto API Docs

Versioning

Project docs API docs (hooks) UI Examples Videos

Services ★★★ ★★★★ ★★★★ ★★★ ★★★★

RestWS ★★★ ★★★★ ★ ★★★★ ★

RESTful ★★★★★ ★★★★★ ★★ ★★★★★ ★★

Endpoint ★★ ★★ ★ ★ ★

Drupal 8 ★★★ ★★★ ★★★ ★★★ ★★★

Documentation & Quick Start

Services RestWS RESTful Endpoint Drupal 8

Popularity

Documentation

Extensibility

Authentication

Performance

Auto API Docs

Versioning

Extensibility & hooks

Services RestWS RESTful Endpoint Drupal 8

Popularity

Documentation

Extensibility

Authentication

Performance

Auto API Docs

Versioning

Total lines of PHP code Without comments, tests and whitespace Hooks

Services 15,000 6,000 18

RestWS 3,000 1,000 7

RESTful 18,000 6,000 1

Endpoint 300 300 -

Drupal 8 5,000 1 3

Code Statistics

ServicesCustom architecture, ~18 hooks (13 — alter)

To create a custom resource:

1. Implement hook_services_resources()

2. Write custom callbacks

RestWSEntity API + 7 hooks

To create a custom resource:

1. Implement hook_restws_resource_info()

2. Create controller class on top of RestWSResourceControllerInterface

RESTfulCtools plugins, Entity API, OOP

To create a custom resource:

1. Implement hook_ctools_plugin_directory ()

2. Create controller class on top of RestfulEntityBase / RestfulInterface

EndpointCustom routing function.

To create a custom resource:

1. Create /api.php with an array of endpoints.

2. Call endpoint_route() from that file.

Drupal 8 RESTPlugin Manager, Config Manager, Routes, Annotations etc.

To create a custom resource:

1. Create controller on top of ResourceBase / ResourceInterface.

2. Save it as src/Plugin/rest/resource/MyCustomResource.php inside your module.

To enable endpoint for existing resource:

3. Write/paste resource settings into rest.settings.yml.

4. Create config/install/rest.settings.yml inside your module.

Services RestWS RESTful Endpoint Drupal 8

Popularity

Documentation

Extensibility

Authentication

Performance

Auto API Docs

Versioning

Security & Authentication

Security & Authentication0. X-CSRF-Token

1. Cookie Auth

2. HTTP Basic Auth

3. Token Auth

4. OAuth

5. Oauth2

X-CSRF-TokenHTTP Header to prevent Cross-Site Request Forgery for session based authentication.

For writing methods: POST, PUT, PATCH, DELETE.

Services RestWS RESTful Endpoint Drupal 8

✔️ ✔️ ✔️ ✖️ ✔️

services/session/token

restws/session/token

api/session/token

rest/session/token

Cookie AuthDrupal build-in auth mechanism.

1. Client sends auth request (user / password).

2. Server returns session cookie in Set-Cookie header.

3. Client makes further requests with Cookie: SESSb7f18cc=pvOhLNLdNNs7BkwbX8… header.

Services RestWS RESTful Endpoint Drupal 8

✔️ ✔️ ✔️ ✔️ ✔️

HTTP Basic AuthUsername and password are sent on every request (base64):

Authorization: Basic aHR0cHdhdGNoOmY=

Services RestWS RESTful Endpoint Drupal 8

✔️ ✔️ ✔️ ✖️ ✔️

Token AuthServer returns token instead of Set-Cookie. { access_token: "7P1bwJtBTSKm-f_UHZFa6m2VWtyLNA8jHRiKUbhNwMQ", type: "Bearer", expires_in: 39584, refresh_token: "Ch9p0Q4KZjisw-vGDzjAQW583bj6He6eiRZOp1ovFLQ" }

(Example from Restful).

Solves some cookies problems with CDNs, session store, CSRF, CORS.

Services RestWS RESTful Endpoint Drupal 8

✖️ ✖️ ✔️ ✖️ ✖️

See #1494132

OAuth implementations in Drupal:

1. OAuth 1.0: https://www.drupal.org/project/oauth

2. OAuth 2.0: https://www.drupal.org/project/oauth2_server

OAuth & OAuth2

Services RestWS RESTful Endpoint Drupal 8

OAuth ✔️ ✖️ ✖️ ✖️ ✖️*

OAuth2 Server ✔️ ✖️ ✔️ ✖️ ✖️

Services RestWS RESTful Endpoint Drupal 8

Popularity

Documentation

Extensibility

Authentication

Performance

Auto API Docs

Versioning

Performance & Speed

How did we count?• Ubuntu 14.04, Nginx 1.8.0, Mariadb 10.0.20, PHP 5.5.9 with php5-fpm, 1GB RAM

• Minimal Drupal Profile

• Node with just Title and Body

• Disabled Drupal cache

• Anonymous requests

• HTTP POST to create entities

• Apache Benchmark (ab)

• Clean database after each ab run

Services RestWS RESTful Endpoint Drupal 8

Popularity

Documentation

Extensibility

Authentication

Performance

Auto API Docs

Versioning

From apiary.io

Services Documentation APIhttps://www.drupal.org/project/services_documentation

Self Documenting REST APIhttps://www.drupal.org/project/rest_api_doc (7.x)

RESTful OPTIONS Request

Self Documenting REST APIhttps://www.drupal.org/project/rest_api_doc (8.x)

Services RestWS RESTful Endpoint Drupal 8

Popularity

Documentation

Extensibility

Authentication

Performance

Auto API Docs

Versioning

1. Versioning API

2. Multiple endpoints: /api/v1, /api/v2/

Versioning in Services

Built-in resource versioning.

Versioning in RESTful

Services RestWS RESTful Endpoint Drupal 8

Popularity

Documentation

Extensibility

Authentication

Performance

Auto API Docs

Versioning

Better to make a difference together

than make it different alone

Leave feedback through Picbackhttp://promokids.github.io/[email protected]@kkomelin

[email protected]@kalabro

Bonus: Drupal as an API Client1. drupal_http_request()/ curl_exec()

2. RESTClient — Wrapper for 1.

3. Guzzle — PHP HTTP client

4. Feeds — for GET only

5. Clients — Pluggable client, supports Services endpoints

6. Remote Entity — Entity API + Clients

7. WSData — Alternative to Remote Entity

8. Integration with popular APIs: Twitter, Facebook, Dropbox etc.

9. Saucier — A Node.JS framework for Drupal API consumption.