27
RESTful webservices: yesterday, today, tomorrow. 1

Restful webservices

Embed Size (px)

DESCRIPTION

RESTful webservices: yesterday, today, tomorrow. Lemberg's presentation for Lviv Euro Drupal Camp 2013. For more articles visit blog.lemberg.co.uk

Citation preview

Page 1: Restful webservices

1

RESTful webservices: yesterday, today,

tomorrow.

Page 2: Restful webservices

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

Page 3: Restful webservices

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 ?

Page 4: Restful webservices

4

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

Page 5: Restful webservices

5

Page 6: Restful webservices

6

Page 7: Restful webservices

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

Page 8: Restful webservices

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

Page 9: Restful webservices

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

Page 10: Restful webservices

10

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

/cats /clients /customers /vehicles

Page 11: Restful webservices

11

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

Define this “non-resource” behavior explicitly

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

Page 12: Restful webservices

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

Page 13: Restful webservices

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

Page 14: Restful webservices

14

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

◦ Pagination◦ Search◦ Collection filtering◦ Partial response

Rule #5: Hide complexity under the “?”

Page 15: Restful webservices

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

Page 16: Restful webservices

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

Page 17: Restful webservices

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.

Page 18: Restful webservices

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.

Page 19: Restful webservices

19

That’s it.

Do not invent custom authorization.

Do not use oAuth-like authorization.

Rule #10: Use oAuth

Page 20: Restful webservices

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)

Page 21: Restful webservices

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

Page 22: Restful webservices

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

Page 23: Restful webservices

23

Combines approaches from Services and RESTWS

Configurable endpoints + Entity API for data management

Services Entity API

Page 24: Restful webservices

24

?

Drupal 8

Page 25: Restful webservices

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?

Page 26: Restful webservices

26

Head of Web development @ Lemberg Solutions

About myself

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

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

Page 27: Restful webservices

27

Thank you!