Роман Паска - RESTful webservices: вчера, сегодня, завтра.

717 views

Published on

Published in: Lifestyle, Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
717
On SlideShare
0
From Embeds
0
Number of Embeds
11
Actions
Shares
0
Downloads
3
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Роман Паска - RESTful webservices: вчера, сегодня, завтра.

  1. 1. 1
  2. 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! 2
  3. 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 3
  4. 4. Web API is a bridge between your application and the rest of the world 4
  5. 5. 5
  6. 6. 6
  7. 7. Is an architectural style, not a strict standard Offers a lot of flexibility Allows to design best practices Provides interfaces that developers love 7
  8. 8. 1. 2. 3. 4. 5. 6. Write documentation Reuse functionality of HTTP protocol Be pragmatic Be consistent Be simple, hide complexity Do not invent custom authorization method 8
  9. 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 9
  10. 10.     /getCat /createCat /getAllClients /newVehicleCustomer     /cats /clients /customers /vehicles 10
  11. 11.   Verbs are okay: /convert?from=UAH&to=USD&amount=100 Define this “non-resource” behavior explicitly 11
  12. 12. 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 Resource POST /cats /cats/123 GET PUT DELETE Create a new List cats cat Bulk update cats Delete all cats - If exists, update cat Delete cat Show cat 12
  13. 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 13
  14. 14.   Keep base URLs structure simple Hide all extra information behind the “?”: ◦ ◦ ◦ ◦ Pagination Search Collection filtering Partial response 14
  15. 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 15
  16. 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 16
  17. 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 17
  18. 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 18
  19. 19. That’s it. Do not invent custom authorization. Do not use oAuth-like authorization. 19
  20. 20. 1. 2. 3. 4. 5. Services (6.x; 7.x): https://drupal.org/project/services RESTful Web Services (7.x): https://drupal.org/project/restws Services Entity API (7.x) http://drupal.org/project/services_entity REST services (7.x) https://drupal.org/sandbox/Taran2L/18073 78 REST in core (8.x) 20
  21. 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) 21
  22. 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 22
  23. 23.   Combines approaches from Services and RESTWS Configurable endpoints + Entity API for data management 23
  24. 24. ? 24
  25. 25.    Hypertext Transfer Protocol -- HTTP/1.1 http://tools.ietf.org/html/rfc2616 Web API Design http://apigee.com/about/content/web-apidesign REST and Serialization in Drupal 8 http://linclark.github.io/d8-rest-slides/ http://www.youtube.com/watch?v=w6dqzDb Y78k 25
  26. 26. Head of Web development @ Lemberg Solutions Taran2L https://drupal.org/user/473438 Roman Paska http://linkedin.com/in/romanpaska/ 26
  27. 27. Thank you! 27

×