Restful webservices
-
Upload
lemberg-solutions -
Category
Technology
-
view
641 -
download
3
description
Transcript of 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!