restful webservices

1

RESTful webservices: yesterday, today,

tomorrow.

2

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!

Disclaimer

3

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

What is this session about ?

4

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

5

6

7

Is an architectural style, not a strict standard

REST (Representational State Transfer):

Offers a lot of flexibility

Allows to design best practices

Provides interfaces that developers love

8

How to design great web APIs1. Write documentation2. Reuse functionality of HTTP protocol3. Be pragmatic4. Be consistent5. Be simple, hide complexity6. Do not invent custom authorization method

9

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

Rule #1: Keep your base URL simple

10

Rule #2a: Do not use verbs in the URLs /getCat /createCat /getAllClients /newVehicleCustomer

/cats /clients /customers /vehicles

11

Verbs are okay:/convert?from=UAH&to=USD&amount=100

Define this “non-resource” behavior explicitly

Rule #2b: Define “non-resource” scenario

12

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

Rule #3: Use HTTP methods as actionsThere are plenty of HTTP methods: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD etcThere are 4 basic operations: Create, Read, Update, Delete (CRUD)

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

13

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

Rule #4: Simplify associations

14

Keep base URLs structure simple Hide all extra information behind the “?”:

◦ Pagination◦ Search◦ Collection filtering◦ Partial response

Rule #5: Hide complexity under the “?”

15

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

Rule #6: Handle errors

16

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

Rule #7: Web APIs version is required parameter

17

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

Rule #8: Use pagination. Allow for a partial response. Define defaults. Be consistent.

18

Respect Accept header Throw an error, if you cannot deliver

response in the expected format (406 Not Acceptable)

Use JSON as a default format

Rule #9: Be smart. Support multiple formats.

19

That’s it.

Do not invent custom authorization.

Do not use oAuth-like authorization.

Rule #10: Use oAuth

20

What does Drupal offer for web APIs1. Services (6.x; 7.x):

https://drupal.org/project/services2. RESTful Web Services (7.x):

https://drupal.org/project/restws3. 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)

21

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)

Services

22

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

RESTful Web Services

23

Combines approaches from Services and RESTWS

Configurable endpoints + Entity API for data management

Services Entity API

24

?

Drupal 8

25

Hypertext Transfer Protocol -- HTTP/1.1 http://tools.ietf.org/html/rfc2616

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

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

What to do next?

26

Head of Web development @ Lemberg Solutions

About myself

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

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

27

Thank you!