1

This presentation is not about Drupal

It’s probably a bit boring: no funny images, no code listings and a lot of text

Still here? Let’s go!

2

Brief web APIs history overview

What is web API

What is REST

How to design great web APIs

What does Drupal offer for web APIs

3

Web API is a bridge between your application and the rest of the world

4

5

6

Is an architectural style, not a strict standard

Offers a lot of flexibility

Allows to design best practices

Provides interfaces that developers love

7

1. Write documentation

2. Reuse functionality of HTTP protocol

3. Be pragmatic

4. Be consistent

5. Be simple, hide complexity

6. Do not invent custom authorization method

8

Use single access point, i.e. api.example.com

There should be only 2 base URLs per resource:

/cats /cats/16

Be consistent: use either singular or plural nouns

Avoid extra abstraction, use concrete names, avoid /items, /assets etc

9

/getCat

/createCat

/getAllClients

/newVehicleCustomer

/cats /clients /customers /vehicles

10

Verbs are okay:

/convert?from=UAH&to=USD&amount=100

Define this “non-resource” behavior explicitly

11

Resource POST GET PUT DELETE

/cats Create a new cat

List cats Bulk update cats

Delete all cats

/cats/123 - Show cat If exists, update cat

Delete cat

There are plenty of HTTP methods: GET, POST, PUT, DELETE, PATCH,

OPTIONS, HEAD etc There are 4 basic operations: Create, Read, Update, Delete (CRUD)

POST => Create, GET => Read, PUT => Update, DELETE => Delete

12

Deep URLs structure is a bad practice, i.e. avoid long URLs:

/client/1/application/2/version/3/terms

Use simple approach: /resource/identifier/resource

13

Keep base URLs structure simple

Hide all extra information behind the “?”: ◦ Pagination

◦ Search

◦ Collection filtering

◦ Partial response

14

Use HTTP status codes

Make error messages as verbose as possible

Use Warning header for any extra information

Provide debug mode (hide under the “?”)

Allow for suppressing this behavior (hide under the “?”):

/cats?suppress_http_errors=true

15

API version number is mandatory

Use a simple ordinal number, i.e. v1, v2

Maintain at least two versions: current and the previous one

Put version in the base URL or in the header

16

All requests should use pagination

Define defaults: number of records and offset

Define pagination: limit & offset

/cats?limit=10&offset=0

Use the same limit and offset for all resources

Allow for a partial response. Hide fields filtering behind the “?”

/cats?fields=name,color,weight

17

Respect Accept header

Throw an error, if you cannot deliver response in the expected format (406 Not Acceptable)

Use JSON as a default format

18

That’s it.

Do not invent custom authorization.

Do not use oAuth-like authorization.

19

1. Services (6.x; 7.x):

https://drupal.org/project/services

2. RESTful Web Services (7.x):

https://drupal.org/project/restws

3. Services Entity API (7.x) http://drupal.org/project/services_entity

4. REST services (7.x) https://drupal.org/sandbox/Taran2L/1807378

5. REST in core (8.x)

20

Relies on the endpoints (custom URLs)

Uses drupal_form_submit() for write operations

Out of the box covers nodes, comments, users only

No default Drupal cookie based authentication (requires explicit authentication with custom hooks)

Great integration with other modules (like Views)

21

Relies on Entity API and metadata about entities

No endpoints: uses /entity_type/1.json or /entity_type/1.xml

Supports any entity type out of the box

Access control on top of Entity API and Field API

Standard user authentication over session cookies or HTTP Basic Auth submodule

22

Combines approaches from Services and RESTWS

Configurable endpoints + Entity API for data management

23

?

24

Hypertext Transfer Protocol -- HTTP/1.1

http://tools.ietf.org/html/rfc2616

Web API Design http://apigee.com/about/content/web-api-design

REST and Serialization in Drupal 8 http://linclark.github.io/d8-rest-slides/ http://www.youtube.com/watch?v=w6dqzDbY78k

25

Head of Web development @ Lemberg Solutions

26

Roman Paska http://linkedin.com/in/romanpaska/

Taran2L https://drupal.org/user/473438

Thank you!

27