REST: Not an Intro

In this session, some common misconceptions about REST are addressed and used as a means to introduce some of the more advanced concepts. Topics include using hypermedia for machine-to-machine interactions, the difference between GET/PUT/POST/DELETE and CRUD, how to (not) do versioning, and why to prefer formats over service interfaces.

Transcript

1. REST: Not an Intro Stefan Tilkov | @stilkov SoundCloud, 2 July 2013
2. REST Intro
3. (not really)
4. identi cation of resources
5. resource manipulation through representations
6. hypermedia as the engine of application state
7. self-descriptive messages
8. What’s in the Web?
9. Lots of things with URLs …
10. … connected with hypermedia …
11. … governed by standard formats.
12. REpresentational State Transfer
13. Common Misconceptions
14. REST is about nice URIs IT’S NOT
15. 1. http://example.com/customers/format?drive=c 2. http://example.com/customers/getDetails?id=13 3. http://example.com/customers/delete?id=13 4. http://example.com/customers/13 5. http://example.com/customers/13/edit What makes a URI “RESTful”?
16. There is no such thing as a “RESTful URI” example.com /customers/delete?id=13 Scheme Path Host Param :// http Opaque ID
17. Why you shouldn’t care about URIs <customer> <...> <orders href=' '> </customer> http://example.com/customers/13/orders http://xyz.org/838892AEF28CDAEFD1234/3 Hypermedia context
18. REST = CRUD NOT AT ALL
19. Minor di erences
20. POST GET PUT DELETE Create Read Update Delete ‣ When used for creation, server decides about URI ‣ Can also invoke arbitrary processing ‣ Can also be used for creation with known URI ‣ Not to be used for partial updates, idempotent
21. Major di erence
22. ‣ Operations on data ‣ Business logic in caller Create Read Update Delete
23. GET PUT POST DELETE (+ Representations + URIs + Hypermedia) ‣Di erent interface style ‣No change in logic responsibilities
24. Data Data Access Business Rules Service Logic Service Interface WSDL SOAP WS-* XML Operations Parameters Messages HTTP JSON XML Resources Hypermedia Representations
25. REST = URI patterns + GET, PUT, POST, DELETE CLOSE, BUT NO
26. URI Method Meaning http://ex.org/v1/customers POST create new customer http://ex.org/v1/customers/{id} GET get customer details http://ex.org/v1/customers{id}/orders GET get list of customer’s details ... ... ... Versions in URIs cause change for no good reason Documented URIs become APIs Assumptions about server details become facts
27. Detour: Versioning
28. What are you “versioning”? Data Documentation Formats APIs ✔ ✔ ✔ ✘
29. Versioning recommendations
30. Use di erent media types for di erent things
31. Use version numbers in URIs to version the resource itself
32. Create new resources for new aspects
33. Reserve space for links
34. Version your docs
35. Wait, what?
36. Yes, no versioning
37. Postel’s law http://tools.ietf.org/html/rfc761 “TCP implementations should follow a general principle of robustness: Be conservative in what you do, be liberal in what you accept from others.”
38. Be kind to each other
39. Postel’s Law Liberal, Loose, Tolerant Strict, Critical, Draconian Liberal, Loose, Tolerant
40. Don’t break URI structure unnecessarily Evolve via additional resources Support older formats Server rules Don’t depend on URI structure Support unknown links Ignore unknown content Client rules
42. How to hypermedia-enable your service interfaces
43. Step 1: Service Documents
44. <?xml version="1.0" encoding="UTF-8"?> <serviceDescription xml:base="http://om.example.com"> <link rel="all" href="/orders/" /> <link rel="received" href="/orders/received/" /> <link rel="accepted" href="/orders/accepted/" /> <link rel="rejected" href="/orders/rejected/" /> <link rel="cancelled" href="/orders/cancelled/" /> <link rel="fulfilled" href="/orders/fulfilled/" /> <link rel="cancellations" href="/cancellations/" /> <link rel="reports" href="/reports/" /> </serviceDescription> <link rel="fulfilled" href="http://om.archive.com/orders/" /> { "serviceDescription" : { "base": "http://om.example.com", "links": [ { "rel": "all", "href": "/orders/" }, { "rel": "all", "href": "/orders/" }, { "rel": "received", "href": "/orders/received/" }, { "rel": "accepted", "href": "/orders/accepted/" }, { "rel": "rejected", "href": "/orders/rejected/" }, { "rel": "cancelled", "href": "/orders/cancelled/" }, { "rel": "fulfilled", "href": "/orders/fulfilled/" }, { "rel": "cancellations", "href": "/cancellations/" }, { "rel": "reports", "href": "/reports/" } ] } }
45. JSON Home { "resources": { "http://example.org/rel/widgets": { "href": "/widgets/" }, "http://example.org/rel/widget": { "href-template": "/widgets/{widget_id}", "href-vars": { "widget_id": "http://example.org/param/widget" }, "hints": { "allow": ["GET", "PUT", "DELETE", "PATCH"], "representations": ["application/json"], "accept-patch": ["application/json-patch"], "accept-post": ["application/xml"], "accept-ranges": ["bytes"] } } } } http://tools.ietf.org/html/dra -nottingham-json-home-03
46. Step 2: Resource Links
47. GET /order/123 { "order": { "date": "2013-07-02", "total": 1240.02, "..." : "...", "links" : [ {"rel" : "self", "href" : "http://example.com/orders/123"}, {"rel" : "contacts", "href" : "http://example.org/A3BEF1"}, ... ] } }
48. GET /order/123 { "order": { "date": "2013-07-02", "total": 1240.02, "..." : "...", "links" : { "self": "http://example.com/orders/123", "contacts": "http://example.org/A3BEF1", ... } } } Your future extensions
49. Step 3: State Transition Links
50. { "order": { "state" : "received", "..." : "...", "links" : [ {"rel" : "cancel", "href" : "http://..."}, {"rel" : "accept", "href" : "http://..."}, {"rel" : "reject", "href" : "http://..."}, ... ] } }
51. Detour: Link Relations
52. <link rel="edit" href="http://..."/> Client Server
53. Web Linking (RFC 5988) HTTP/1.1 200 OK Link: <http://om.com/orders/?page=2>;rel="prev" Link: <http://om.com/orders/?page=4>;rel="next" HTTP/1.1 200 OK Link: <htt://xyz.com>;rel="http://example.com/rels/own" Link: <http://xyz.com>;rel="prev" Link: <http://xyz.com>; rel="http://www.iana.org/assignments/relation/prev"
55. Hypermedia APIs = Responses with Links NOT ONLY
56. Rule #1: Don’t have clients build URIs using string concatenation
57. …instead: provide recipes
58. <form action='http://example.com/search' method='GET'> Search for: <input type='text' name='query'> <input type='submit'> </form> { "rel": "search", "template": "http://example.com/search?q={query}" }
59. <form action='http://example.com/add' method='POST'> First: <input type='text' name='first'> Last: <input type='text' name='last'> Birthday: <input type='date' name='bdate'> <input type='Add'> </form> {"target": "http://example.com/add", "rel": "add", "template": { "first": "...", "last": "...", "bdate": "..." } }
60. REST = A di erent approach to service interfaces TOO SIMPLE
61. System B Point-to-point integration System A
62. Client 1 Service interfaces Server Client 2 Client n …
63. Client 1 Hypermedia types Client 2 Client n … Server A Server B Server n … Format
64. application/atom+xml
65. application/opensearchdescription+xml
66. application/vnd.collection+json
67. application/hal+json
68. text/html
69. Detour: HTML
70. <order> <shippingAddress>Paris, France</shippingAddress> <items> <item> <productDescription>iPad</productDescription> <quantity>1</quantity> <price>699</price> </item> </items> <link href="http://om.example.com/cancellations" rel="cancel" /> <link href="https://om.example.com/orders/123/payment" rel="payment" /> </order>
71. <html xmlns="http://www.w3.org/1999/xhtml"> <body> <div class="order"> <p class="shippingAddress">Paris, France</p> <ul class="items"> <li class="item"> <p class="productDescription">iPad</p> <p class="quantity">1</p> <p class="price">699</p> </li> </ul> <a href="http://om.example.com/cancellations" rel="cancel">cancel</a> <a href="https://om.example.com/orders/123/payment" rel="payment">payment</a> </div> </body> </html>
72. http://schema.org
73. <div> <h1>Avatar</h1> <span>Director: <span>James Cameron</span> (born August 16, 1954)</span> <span>Science fiction</span> <a href="../movies/avatar-theatrical-trailer.html"</a> </div>
74. <div itemscope itemtype="http://schema.org/Movie"> <h1>Avatar</h1> <span>Director: <span>James Cameron</span> (born August 16, 1954)</span> <span>Science fiction</span> <a href="../movies/avatar-theatrical-trailer.html"</a> </div>
75. <div itemscope itemtype="http://schema.org/Movie"> <h1 itemprop="name">Avatar</h1> <span>Director: <span itemprop="director">James Cameron</span> (born August 16, 1954)</span> <span itemprop="genre">Science fiction</span> <a href="../movies/avatar-theatrical-trailer.html" itemprop="trailer">Trailer</a> </div>
77. Summary
78. Link context over pretty URIs
79. Process logic over CRUD
80. Hypermedia over URI APIs
81. Hypermedia flows over static links
82. Generalized formats over services
83. Q&A Stefan Tilkov, @stilkov stefan.tilkov@innoq.com Phone: +49 170 471 2625 innoQ Deutschland GmbH Krischerstr. 100 40789 Monheim am Rhein Germany Phone: +49 2173 3366-0 innoQ Schweiz GmbH info@innoq.com Gewerbestr. 11 CH-6330 Cham Switzerland Phone: +41 41 743 0116 www.innoq.com Ohlauer Straße 43 10999 Berlin Germany Phone: +49 2173 3366-0 Robert-Bosch-Straße 7 Germany Phone: +49 2173 3366-0 Radlkoferstraße 2 D-81373 München Telefon +49 (0) 89 741185-270