REST: Not an Intro

There is probably no developer left who hasn't been exposed to at least one introduction to REST, and most have by now gathered some first-hand experience. After the world's shortest introduction to REST we'll dive into more advanced stuff, such as common misconceptions, hypermedia aspects, format/resource/representation alternatives, and implementation issues - with room for lots of questions (and hopefully, answers).

Transcript

1. REST: Not an Intro Stefan Tilkov | @stilkov GOTO Night, 23 September 2013
2. REST Intro
3. (not really)
4. identification 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 differences
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 difference
22. ‣ Operations on data ‣ Business logic in caller Create Read Update Delete
23. GET PUT POST DELETE (+ Representations + URIs + Hypermedia) ‣Different 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 different media types for different 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/draft-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. Hypermedia APIs = Responses with Links NOT ONLY
52. Rule #1: Don’t have clients build URIs using string concatenation
53. …instead: provide recipes
54. <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}" }
55. <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='submit'> </form> {"target": "http://example.com/add", "rel": "add", "template": { "first": "...", "last": "...", "bdate": "..." } }
56. REST = A different approach to service interfaces TOO SIMPLE
57. System B Point-to-point integration System A
58. Client 1 Service interfaces Server Client 2 Client n …
59. Client 1 Hypermedia types Client 2 Client n … Server A Server B Server n … Format
60. application/atom+xml
61. application/opensearchdescription+xml
62. application/vnd.collection+json
63. application/hal+json
64. text/html
65. Detour: HTML
66. <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>
67. <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>
68. http://schema.org
69. <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>
70. <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>
71. <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>
73. Summary
74. Link context over pretty URIs
75. Process logic over CRUD
76. Hypermedia over URI APIs
77. Hypermedia flows over static links
78. Generalized formats over services
79. 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 64293 Darmstadt Germany Phone: +49 2173 3366-0 Radlkoferstraße 2 D-81373 München Telefon +49 (0) 89 741185-270