REST & ROCA: Slightly more than an Introduction

An overview of both topics, including some common REST misconceptions.

Transcript

1. REST & ROCA: Slightly more than an Introduction Stefan Tilkov | innoQ | @stilkov
3. http://rest-http.info
4. REpresentational State Transfer Roy Fielding, http://www.ics.uci.edu/~ elding/pubs/dissertation/top.htm
5. The REST Uniform Interface identification of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages
6. The REST Uniform Interface http://example.com/orders?year=2008 http://example.com/customers/1234 http://example.com/orders/2007/10/776654 http://example.com/products/4554 http://example.com/processes/sal-increase-234 identification of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages identification of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages
7. The REST Uniform Interface GET /customers/1234 Host: example.com Accept: application/vnd.mycompany.customer+xml <customer>...</customer> GET /customers/1234 Host: example.com Accept: text/x-vcard begin:vcard ... end:vcard identification of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages
8. The REST Uniform Interface <order self='http://example.com/orders/3321'> <item> <amount>23</amount> <product ref='http://example.com/products/4554' /> </item> <customer ref='http://example.com/customers/1234' /> <link rel='items' ref='http://example.com/orders/3321/items' /> </order> identification of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages
9. The REST Uniform Interface identification of resources resource manipulation through representations hypermedia as the engine of application state self-descriptive messages GET /service/customers/1234 HTTP 1.1 Host: www.example.com User-Agent: XYZ 1.1 Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Keep-Alive: 300 Connection: keep-alive If-Modified-Since: Fri, 02 Oct 2009 16:47:31 GMT If-None-Match: "600028c-59fb-474f6852c9dab" Cache-Control: max-age=60 HTTP/1.1 200 OK Date: Sun, 04 Oct 2009 19:36:25 GMT Server: Apache/2.2.11 (Debian) Last-Modified: Fri, 02 Oct 2009 16:47:31 GMT Etag: "600028c-59fb-474f6852c9dab" Cache-Control: max-age=300 Accept-Ranges: bytes Vary: Accept-Encoding Content-Encoding: gzip Content-Length: 7160 Keep-Alive: timeout=15, max=91 Connection: Keep-Alive Content-Type: application/xml <?xml version=‘1.0’ encoding=‘utf-8’ ?> ... Standard Method Media Type Data Control Data Visibility
10. getOrderDetails() updateQuote() cancelSubscription() findMatchingBid() initiateProcess() submitApplicationData() listAuctions() getUsers()
11. updateQuote() cancelSubscription() findMatchingBid() initiateProcess() submitApplicationData() listAuctions() getUsers() getOrderDetails() GET PUT POST DELETE
12. interface Resource { Resource(URI u) Response get() Response post(Request r) Response put(Request r) Response delete() } generic specific class CustomerCollection : Resource { ... Response post(Request r) { id = createCustomer(r) return new Response(201, r) } ... } Any HTTP client (Firefox, IE, curl, wget) Any HTTP server Caches Proxies Google, Yahoo!, MSN Anything that knows your app
14. Common Misconceptions
15. Standard methods are not Enough WRONG
16. many very few (one per service) many
17. very few (fixed) many many
18. getFreeTimeSlots(Person) →GET /people/st/timeslots?state=free rejectApplication(Application) →POST /rejections↵ <application>http://...</application>↵ <reason>Unsuitable for us!</reason> performTariffCalculation(Data) →POST /contracts↵ Data ←Location: http://.../contracts/4711 <tariff ref=’./contracts/4711/tariff’ /> →GET /contracts/4711/tariff ←Result shipOrder(ID) →PUT /orders/0815/status↵ <status>shipped</status> shipOrder(ID) [variation] →POST /shipments↵ Data ←Location: http://.../shipments/4711
19. REST o ers less standardization than SOAP/WSDL/WS-* Web services WRONG
20. (“REST” is not a standard)
21. Standardized with RESTful HTTP Identity Methods Content (Format) Negotiation Caching Compression Chunking Authentication
22. REST is for easy things, WS-* for complex ones UNTRUE
23. easy simple complex hard
24. REST is for services only WRONG
25. REST as the Web’s Architectural Style 1991 HTTP 0.9 1996 HTTP 1.0 1997 HTTP 1.1 (RFC 2068) 1999 HTTP 1.1 (RFC 2616) 2000 REST 2000 SOAP/1.1 Browsers Command line clients Proxies Servers Crawlers
26. ROCA http://roca-style.org/
27. (Resource-oriented Client Architecture)
28. Web-centric web UIs
29. Server-side components Avoid HTML, JS, CSS Trade Familiarity for Complexity Session-centric ROCA Server-side POSH Client-side components Web-centric Single Page Apps Advanced Client Frameworks Server-side REST APIs
30. Make your HTML semantic
31. Minimal load times API usage Accessibility Self-descriptiveness Readability
32. CSS HTML Content Layout
33. “HTML?” “I don’t do that – I’m a programmer.”
34. <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>
35. <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>
36. schema.org <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>
37. schema.org <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>
38. schema.org <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>
39. Use Javascript unobtrusively
40. <a href="javascript:doSomething();"> Some Link </a>
41. <a href="#" onclick="doSomething();"> Some Link </a>
42. <a href="/some-resource" onclick="doSomething(this.href);"> Some Link </a>
43. <a href="/some-resource" class="whatever"> Some Link </a>
44. $("a.whatever").click(function() { doSomething(this.href); }); + <a href="/some-resource" class="whatever"> Some Link </a>
45. <div id="tabs"> <ul> <li><a href="#tabs-1">Nunc tincidunt</a></li> <li><a href="#tabs-2">Proin dolor</a></li> <li><a href="#tabs-3">Aenean lacinia</a></li> </ul> <div id="tabs-1"> <p>Proin elit arcu, rutrum commodo, vehicula ...</p> </div> <div id="tabs-2"> <p>Morbi tincidunt, dui sit amet facilisis feugiat, odio ...</p> </div> <div id="tabs-3"> <p>Mauris eleifend est et turpis. Duis id erat ...</p> </div> $("#tabs").tabs(); +
47. $('.multiselect', context).each(function() { $(this).multiselect({ selectedList: 2, checkAllText: "All", uncheckAllText: "None" }).multiselectfilter({label:"", width:"200px"}); }); <div class="filter-column"> <label for="project">Project</label> <select class="multiselect" id="project" name="project" size="5" multiple> <option>DISCOVER</option> <option>IMPROVE</option> <option >MAGENTA</option> <option>ROCA</option> <option>ROCKET</option> </select> </div>
48. CSS HTML Content Layout
49. JavaScript CSS HTML Content Behavior Layout
50. JS component JS glue code HTML Events Methods Component 2 Component 3 ... Layout/CSS styles styles Server / Backend Ajax initializes Base Markup responds with
51. Use URIs to identify a single meaningful concept
52. A http://.../A
53. A B C http://.../A ?
54. A http://.../A C http://.../C B http://.../B b c + AJAX + CSS
55. A B C http://.../A
56. Don’t disable Browser Features – use them
57. Multiple tabs & windows Bookmarks Back/Forward/Refresh Personalization Menus
58. Put application logic on the server only
59. Don’t trust your clients RESTful APIs for free Non-browser clients (e.g. Google Crawler)
60. Avoid session state
61. Browser Server HTML Page Label Label Label Label Label Label Label Label Submit
62. Browser Server Label Label Label Next Label Label Label Next Label Label Finish Session State
63. Browser Server Label Label Label Next Label Label Label Next Label Label Finish HTML Page Label Label Label Label Label Label Label Label Submit Client State
64. Server HTML Page Label Label Label Label Label Label Label Label Submit HTML Page Label Label Label Label Label Label Label Label Submit HTML Page Label Label Label Label Label Label Label Label Submit
65. ROCA http://roca-style.org/
66. REST is about nice URLs IT’S NOT
67. http://example.com/customers/getDetails?id=13 http://example.com/customers/delete?id=13 http://example.com/customers/13 http://example.com/customers/13/orders http://example.com/orders/4711/customer What makes a URI “RESTful”?
68. There is no such thing as a “RESTful URI” example.com /customers/delete?id=13 Scheme Path Host Param :// http Opaque ID
69. Why you shouldn’t care about URIs <customer> <...> <orders href=' '> </customer> http://example.com/customers/13/orders http://xyz.org/838892AEF28CDAEFD1234/3 Hypermedia context
70. REST = CRUD NOT AT ALL
71. Minor di erences POST GET PUT 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 Create Read Update Delete
72. Major di erence GET, PUT, POST, DELETE (+ Representations + URIs + Hypermedia) ‣Operations on data ‣Pure storage; business logic in caller Create, Read, Update, Delete ‣Di erent interface style ‣No change in logic responsibilities
73. Data Data Access Business Rules Service Logic Service Interface WSDL SOAP WS-* XML Operations Parameters Messages HTTP JSON XML Resources Hypermedia Representations
74. 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 IDs cause change without reason Documented URIs become APIs Inflexible assumptions about server details
75. Step 1: Service Documents Document with links to “entry point” resources Can be consumer-speci c Additional “cheap” decoupling Federated if necessary
76. Service documents <services> <service id="lookup" href="http://..."/> <service id="crm" href="http://..."/> <service id="accounting" href="http://..."/> </services>
77. Example <?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/" /
78. Link styles <service id="lookup" href="http://..."/> <link rel="service" name="lookup" href="http://..."/> <link rel="lookup-service" href="http://..."/>
79. Step 2: Resource Links Inherited from your domain model Links between collection- and primary resources Links for self-references Make even implicit relationships explicit to prevent client-side assumptions
80. Step 3: State Transition Links Determine the possible client actions Distinction from resource links is leaky since every link acts as state transition
81. “Named” Links Resource relationships in representations Independence from URI design Possible “De-Co-Location”
82. Link Relations <?xml version="1.0" encoding="UTF-8"?> <order xml:base="http://om.example.com"> <link rel="self" href="/orders/123" type="application/vnd.example.com-ordermgr+xml" / > <state>received</state> <link rel="payment" href="https://paypal/" /> <link rel="cancel" href="/cancellations/" /> <!-- ... --> </order> <?xml version="1.0" encoding="UTF-8"?> <orders xmlns="http://example.com/schemas/ordermanagement" xml:base="http://om.example.com"> <link rel="self" href="/orders/?page=3" /> <link rel="prev" href="/orders/?page=2" /> <link rel="next" href="/orders/?page=4" /> <!-- ... --> </orders>
83. <link rel="edit" href="http://..."/> Client Server
84. Summary
85. REST is quickly becoming mainstream
86. Many things that claim to be REST, aren’t
87. REST without Hypermedia, a.k.a. “Web without links: Common ≠ Good
88. REST is not for “services” only
89. 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