REST and other important stuff

Transcript

1. Representational State Transfer (REST) (and some other important stuff) woensdag 25 april 12
2. Warning before we start ‣ REST != MVC ‣ Do not think in controllers, id’s, actions, models, views, plugins, helpers etc... ‣ In fact, do not think about implementation AT ALL!! woensdag 25 april 12
3. What is REST? REST is a coordinated set of architectural constraints that attempts to minimize latency and network communication while at the same time maximizing the independence and scalability of component implementations. This is achieved by placing constraints on connector semantics where other styles have focused on component semantics. REST enables the caching and reuse of interactions, dynamic substitutability of components, and processing of actions by intermediaries, thereby meeting the needs of an Internet-scale distributed hypermedia system. Roy Fielding said: woensdag 25 april 12
4. What is REST? ‣ ADVANTAGES OF REST ‣ Cacheable ‣ Stateless ‣ Scalable ‣ Fault-tolerant ‣ Loosely coupled woensdag 25 april 12
5. What is REST? ‣ URL identifies a resource ‣ URLs have an hierarchy ‣ Methods perform operations on resources ‣ Operation must be implicit ‣ Hypermedia format to represent data ‣ Link relations to navigate ‣ THE PRINCIPLES OF REST woensdag 25 april 12
6. What is REST? ‣ THE FOUR MAIN PRINCIPLES ‣ Identification of resources ‣ Manipulation of resources ‣ Self-descriptive messages ‣ HATEOAS woensdag 25 april 12
7. What is REST? ‣ THE FOUR MAIN PRINCIPLES ‣ Identification of resources ‣ Manipulation of resources ‣ Self-descriptive messages ‣ HATEOAS woensdag 25 april 12
8. Identification of resources ‣ /index.php?action=getarticle&id=5 ‣ /default/article/5/4/6/size ‣ You are doing it wrong... :( Cacheable? Scalable? Readable? woensdag 25 april 12
9. Identification of resources ‣ /articles ‣ /articles/5/photos/4/comments/1 ‣ /articles/5/photos/4/comments We want the first comment of the fourth photo for the fifth article We want all comments of the fourth photo for the fifth article We want all articles Cacheable! Scalable! Readable! ‣ Readable and maintainable! woensdag 25 april 12
10. Identification of resources ✗ /photos/order/size/limit/5 ✗ /photos/limit/5/order/size ✓ /photos?order=size&limit=5 ✓ /photos?limit=5&order=size ‣ FILTERING THROUGH A QUERY STRING, NOT THE URI woensdag 25 april 12
11. What is REST? ‣ THE FOUR MAIN PRINCIPLES ‣ Identification of resources ‣ Manipulation of resources ‣ Self-descriptive messages ‣ HATEOAS woensdag 25 april 12
12. Manipulation of resources ‣ Create ‣ Retrieve ‣ Update ‣ Delete ‣ But please note that REST != CRUD woensdag 25 april 12
13. Manipulation of resources ‣ Create = PUT ‣ Retrieve = GET ‣ Update = POST ‣ Delete = DELETE ‣ CRUD to HTTP verb mapping woensdag 25 april 12
14. Manipulation of resources ‣ SAFE METHODS ‣ Any client should be able to make the request as many times as necessary. ‣ GET, OPTIONS, HEAD woensdag 25 april 12
15. Manipulation of resources ‣ IDEMPOTENT METHODS ‣ Garantuees that the client can repeat the request when it’s not certain. ‣ $x++ vs $x=4 ‣ ALL METHODS EXCEPT “POST” woensdag 25 april 12
16. What is REST? ‣ THE FOUR MAIN PRINCIPLES ‣ Identification of resources ‣ Manipulation of resources ‣ Self-descriptive messages ‣ HATEOAS woensdag 25 april 12
17. Self-descriptive messages ‣ Stateless! ‣ All information for processing is available: ‣ How? (method + content-type) ‣ What? (URI) ‣ When? (preconditions) ‣ Who? (authentication) woensdag 25 april 12
18. Self-descriptive messages GET /article/1234 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version: 1.0 Authorization: OAuth oauth_nonce=”123” ... If-None-Matched: absad12412414 ‣ HOW (method) woensdag 25 april 12
19. Self-descriptive messages GET /article/1234 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version: 1.0 Authorization: OAuth oauth_nonce=”123” ... If-None-Matched: absad12412414 ‣ HOW (content-type) woensdag 25 april 12
20. Self-descriptive messages GET /article/1234 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version: 1.0 Authorization: OAuth oauth_nonce=”123” ... If-None-Matched: absad12412414 ‣ WHAT woensdag 25 april 12
21. Self-descriptive messages GET /article/1234 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version: 1.0 Authorization: OAuth oauth_nonce=”123” ... If-None-Matched: absad12412414 ‣ WHEN woensdag 25 april 12
22. Self-descriptive messages GET /article/1234 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version: 1.0 Authorization: OAuth oauth_nonce=”123” ... If-None-Matched: absad12412414 ‣ WHO woensdag 25 april 12
23. What is REST? ‣ THE FOUR MAIN PRINCIPLES ‣ Identification of resources ‣ Manipulation of resources ‣ Self-descriptive messages ‣ HATEOAS woensdag 25 april 12
24. HATEOAS HATEOAS = Hypermedia As The Engine Of Application State woensdag 25 april 12
25. HATEOAS This is the hardest and of course, most important part of REST woensdag 25 april 12
26. HATEOAS ‣ Use links to allow clients to discover locations and operations. ‣ Link relations are used to express options. ‣ Clients do not need to know URLs. ‣ This controls the state. woensdag 25 april 12
27. State inside your REST API ‣ “Flight booking API” Select Confirm Pay Fetch E-Ticket woensdag 25 april 12
28. State inside your REST API ‣ Search for specified flights POST /search?order=price&limit=5 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version: 1.0 <search> <destination>LPA</destination> <date>24-may-2011</date> <type>firstclass</type> </search> woensdag 25 april 12
29. State inside your REST API ‣ Returns a collection of flights HTTP/1.1 200 OK Content-type: application/vnd.enrise.nl+xml ; version: 1.0 <flights xmlns=...> <flight> <flightno>KL1234</flightno> <time>4:24</time> <link method=”get” rel=”details” action=”/flight/15263” type=”text/xml”> <link method=”post” rel=”confirm” action=”/confirm/flight/15263” type=”text/xml”> </flight> <flight> <flightno>HV123</flightno> <time>3:54</time> <link method=”get” rel=”details” action=”/flight/523525” type=”text/xml”> <link method=”post” rel=”confirm” action=”/confirm/flight/523525” type=”text/xml”> </flight> </flights> woensdag 25 april 12
30. State inside your REST API ‣ Confirm a specific flight POST /confirm/flight/15263 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version: 1.0 <flight> <seat>2A</seat> <meal>vegetarian</meal> </flight> HTTP/1.1 401 Authentication required woensdag 25 april 12
31. State inside your REST API ‣ Confirm a specific flight, with more info POST /confirm/flight/15263 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version: 1.0 Authorization: OAuth ...... <flight> <seat>2A</seat> <meal>vegetarian</meal> </flight> HTTP/1.1 200 OK Location: /booking/1616163 <booking> <link rel=”details” href=”/booking/1616163” method=”get” type=”application/xml”> <link rel=”payment” href=”/payment/booking/1616163” type=”application/xml”> <link rel=”cancel” href=”/booking/1616163” method=”delete” type=”application/xml”> </booking> woensdag 25 april 12
32. State inside your REST API ‣ What can we do with our booking? OPTIONS /booking/1616163 HTTP/1.1 Host: www.enrise.com Authorization: OAuth ...... HTTP/1.1 200 OK Allow: GET, DELETE, PUT woensdag 25 april 12
33. State inside your REST API ‣ Cancel our booking! DELETE /booking/1616163 HTTP/1.1 Host: www.enrise.com Authorization: OAuth ...... HTTP/1.1 204 No content woensdag 25 april 12
34. State inside your REST API ‣ Still need to pay for the flight GET /booking/1616163 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version: 1.0 Authorization: OAuth... HTTP/1.1 200 OK <booking> <flight> <flightno>KL1234</flightno> <time>4:24</time> <link rel=”details” method=”get” href=”/flight/15263”> </flight> <payment> <status>Not paid</status> <link rel=”details” method=”get” href=”/payment/booking/1616163”> <link rel=”pay” method=”post” href=”/payment/booking/1616163”> </payment> </booking> woensdag 25 april 12
35. State inside your REST API ‣ Pay through another resource PUT /payment/booking/1616163 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version: 1.0 Authorization: OAuth ...... <payment> <cardno>4111-1111-1111-1111</cardno> <expires>04/13</expires> <name>Joshua Thijssen</name> <amount currency=”eur”>414.00</amount> </payment> HTTP/1.1 201 Created Location: /payment/booking/1616163 woensdag 25 april 12
36. State inside your REST API ‣ Can’t delete our booking since it’s paid OPTIONS /booking/1616163 HTTP/1.1 Host: www.enrise.com Authorization: OAuth ...... HTTP/1.1 200 OK Allow: GET woensdag 25 april 12
37. State inside your REST API ‣ We can fetch our eticket now GET /booking/1616163 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version: 1.0 Authorization: OAuth... HTTP/1.1 200 OK <booking> <flight> <flightno>KL1234</flightno> <time>4:24</time> <link rel=”details” method=”get” href=”/flight/15263”> </flight> <payment> <status>Paid in full</status> <link rel=”details” method=”get” href=”/payment/booking/1616163”> </payment> <link rel=”eticket” method=”get” href=”/eticket/12415156261616”> </booking> woensdag 25 april 12
38. (Common) pitfalls of REST design ‣ Versioning ‣ Methods in uri ‣ One uri per resource ‣ Controller resources & non-CRUD woensdag 25 april 12
39. (Common) pitfalls of REST design ‣ Versioning ‣ Methods in uri ‣ One uri per resource ‣ Controller resources & Non-CRUD woensdag 25 april 12
40. (Common) pitfalls of REST design ‣ /api/v1.1/article/1234/photos ‣ /api/v1.2/article/1234/photos ‣ Different resources? ‣ Versioning woensdag 25 april 12
41. (Common) pitfalls of REST design GET /api/article/1234/photos HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version = 1.0 GET /api/article/1234/photos HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+json ; version = 1.1 ‣ Versioning GET /api/article/1234/photos HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+json ; version = 5.0.4a woensdag 25 april 12
42. (Common) pitfalls of REST design ‣ Versioning ‣ Methods in uri ‣ One uri per resource ‣ Controller resources & Non-CRUD woensdag 25 april 12
43. (Common) pitfalls of REST design ‣ /api/get/articles/1234/photos ‣ /api/articles/new ‣ /api/articles/list ‣ Methods in URL woensdag 25 april 12
44. (Common) pitfalls of REST design ‣ Versioning ‣ Methods in uri ‣ One uri per resource ‣ Controller resources & Non-CRUD woensdag 25 april 12
45. (Common) pitfalls of REST design ‣ /api/article/1234 ‣ /api/article/red+teddybear ‣ Different resources ‣ One URI per resource woensdag 25 april 12
46. (Common) pitfalls of REST design GET /api/article/red+teddybear HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version = 1.0 HTTP/1.1 303 See Other Location: /api/article/1234 ‣ One URI per resource woensdag 25 april 12
47. (Common) pitfalls of REST design ‣ Versioning ‣ Methods in uri ‣ One uri per resource ‣ Controller resources & Non-CRUD woensdag 25 april 12
48. (Common) pitfalls of REST design ‣ Outside the CRUD? ‣ Multiple operations simultaneously? ‣ Controller resources & non-crud woensdag 25 april 12
49. (Common) pitfalls of REST design POST /distance HTTP/1.1 Host: www.enrise.com Accept: text/xml Content-type: text/xml;charset=UTF-8 <xml> <from>Amersfoort, NLD</from> <to>Apeldoorn, NLD</to> </xml> HTTP/1.1 200 OK Content-length: 123 Content-type: text/xml <result> <distance unit=”km”>45</distance> <distance unit=”miles”>27.96</distance> </result> ‣ Controller resources & non-crud GET /distance?from=...&to=.. HTTP/1.1 Host: www.enrise.com Accept: text/xml woensdag 25 april 12
50. (Common) pitfalls of REST design POST /user/jthijssen/address_merge HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version = 1.0 Content-type: text/csv;charset=UTF-8 John Doe, 1 Main Street, Seattle, WA Jane Doe, 100 North Street, Los Angeles, CA HTTP/1.1 303 See Other Location: /user/jthijssen/addressbook ‣ Controller resources & non-crud woensdag 25 april 12
51. More important stuff ‣ HTTP Status codes ‣ ETags woensdag 25 april 12
52. HTTP Status codes ‣ Status codes are important ‣ They represent the result of your actions woensdag 25 april 12
53. HTTP Status codes ‣ 1xx ‣ 2xx ‣ 3xx ‣ 4xx ‣ 5xx Informational Success Redirection Client error Server error woensdag 25 april 12
54. HTTP Status codes ‣ 200 OK ‣ 201 Created ‣ 204 No content ‣ IMPORTANT 2xx CODES Resource returned Resource created Resource deleted woensdag 25 april 12
55. HTTP Status codes ‣ 304 Not modified ‣ IMPORTANT 3xx CODES Resource wasn’t changed woensdag 25 april 12
56. HTTP Status codes ‣ 400 Bad request ‣ 401 Unauthorized ‣ 403 Forbidden ‣ 404 Not found ‣ IMPORTANT 4xx CODES Resource was not found Not authorized to operate Not authorized to operate Incorrect payload woensdag 25 april 12
57. HTTP Status codes ‣ 405 Method not allowed ‣ 406 Not acceptable ‣ 412 Precondition failed ‣ IMPORTANT 4xx CODES Method incorrect “ETag mismatch” Cannot return in correct format woensdag 25 april 12
58. HTTP Status codes ‣ 500 Internal server error ‣ 501 Not implemented ‣ IMPORTANT 5xx CODES “Something” happened Method is not implemented woensdag 25 april 12
59. HTTP Status codes ‣ 501 Not implemented vs 405 Method not allowed ‣ 409 Conflict vs 412 Precondition failed ‣ de·bat·a·ble/diˈbātəbəl/Adjective woensdag 25 april 12
60. ETags & Optimistic locking GET /blogpost/12345 HTTP/1.1 Host: www.enrise.com HTTP/1.1 200 OK Content-length: 1234000 Content-type: text/xml ETag: abcd-1234 <xml> <blogpost> <author>Joshua Thijssen</author> <title>...</title> .... </blogpost> </xml> woensdag 25 april 12
61. ETags & Optimistic locking GET /blogpost/12345 HTTP/1.1 Host: www.enrise.com If-None-Match: abcd-1234 HTTP/1.1 304 Not modified Blogpost is cached and can be used! woensdag 25 april 12
62. ETags & Optimistic locking POST /blogpost/12345 HTTP/1.1 Host: www.enrise.com If-Match: abcd-1234 <xml> <author>Sjors de Valk</author> </xml> HTTP/1.1 412 Precondition failed Blogpost is already modified by “someone” woensdag 25 april 12
63. REST examples Other REST Examples woensdag 25 april 12
64. REST examples ‣ Creating a resource PUT /articles HTTP/1.1 Host: www.enrise.com Content-type: application/vnd.enrise.nl+xml ; version = 1.0 <article xmlns=”http://www.enrise.com/article”> <name>Teddybear</name> <color>red</color> <stock>15</stock> <price currency=”eur”>15,95</price> <price currency=”usd”>19,95</price> </article> HTTP/1.1 201 Created Location: /articles/1234 woensdag 25 april 12
65. REST examples ‣ Getting a resource collection GET /articles HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version = 1.0 HTTP/1.1 200 OK Content-length: 12345 Content-type: application/vnd.enrise.nl+xml Date: sun, 01 Nov 2010 12:34:56 GMT <articles xmlns=”http://www.enrise.com/article”> <article> <name>Teddybear</name> <link method=”get” rel=”article” href=”/articles/1234”> </article> <article> <name>Skippyball</name> <link method=”get” rel=”article” href=”/articles/1121”> </article> </articles> woensdag 25 april 12
66. REST examples ‣ Getting a resource GET /articles/1234 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version = 1.0 HTTP/1.1 200 OK Content-length: 12345 Content-type: application/vnd.enrise.nl+xml Date: sun, 01 Nov 2010 12:34:56 GMT <article xmlns=”http://www.enrise.com/article”> <name>Teddybear</name> ... </article> HTTP/1.1 404 Not found Content-length: 0 Date: sun, 01 Nov 2010 12:34:56 GMT woensdag 25 april 12
67. REST examples ‣ Delete a resource DELETE /articles/1234 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version = 1.0 HTTP/1.1 204 No content Content-length: 0 Date: sun, 01 Nov 2010 12:34:56 GMT woensdag 25 april 12
68. REST examples ‣ Updating a resource POST /articles/1234 HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version = 1.0 If-Match: 23709-12135125 <article xmlns=”http://www.enrise.com/article> <name>Teddybear</name> <color>red</color> <stock>30</stock> <price currency=”eur”>15,95</price> <price currency=”usd”>19,95</price> </article> HTTP/1.1 200 OK Content-length: 0 Date: sun, 01 Nov 2010 12:34:56 GMT HTTP/1.1 412 Precondition failed Content-length: 0 Date: sun, 01 Nov 2010 12:34:56 GMT Idempotent woensdag 25 april 12
69. (Common) pitfalls of REST design POST /user/jthijssen/address_merge HTTP/1.1 Host: www.enrise.com Accept: application/vnd.enrise.nl+xml ; version = 1.0 Content-type: text/csv;charset=UTF-8 John Doe, 1 Main Street, Seattle, WA Jane Doe, 100 North Street, Los Angeles, CA HTTP/1.1 303 See Other Location: /user/jthijssen/addressbook ‣ Controller resources woensdag 25 april 12
70. More reading ‣ http://en.wikipedia.org/wiki/Representational_State_Transfer ‣ http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm ‣ http://oreilly.com/catalog/9780596801694 ‣ http://www.slideshare.net/Wombert/designing-http-interfaces-and- restful-web-services-confoo11-20110310 ‣ http://www.slideshare.net/adorepump/hateoas-the-confusing-bit- from-rest ‣ http://www.slideshare.net/guilhermecaelum/rest-in-practice woensdag 25 april 12
71. Question & discussion http://farm1.static.flickr.com/73/163450213_18478d3aa6_d.jpg woensdag 25 april 12
72. ‣ THANK YOU FOR YOUR ATTENTION woensdag 25 april 12