Роман Паска - restful webservices: вчера, сегодня, завтра
TRANSCRIPT
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