29. PROBLEMS WITH THIS API• Always a POST• Doesnt use HTTP Authentication• Operation information is enclosed in the request ("getdetail")• Nothing there is cacheable• Everything through one endpoint (/api/talks for talks)
30. Level 0 in the Richardson Maturity Model: Plain old XML over the wire in an RPC fashion
31. Room for improvement: use one URI for each resource.
32. That would be Level 1 in Richardsons Maturity Model
33. Level 0 and Level 1 are a bag of hurt. Do not use them. Ever.
34. ALONG CAME ROY FIELDING And Gave Us REST
35. that was awesome
36. because everyone could say
37.  I haz REST nao
38. when in fact
39. they bloody didn’t
40. RESTWhat Does That Even Mean?
41. REpresentational State Transfer
42. Roy Thomas Fielding: Architectural styles andthe design of network based software architectures.
45. •A URL identiﬁes a Resource• The URLs have an implicit hierarchy • so you know that something with additional slashes is a subordinate resource (HTTP spec)• Methods perform operations on resources• The operation is implicit and not part of the URL•A hypermedia format is used to represent the data• Link relations are used to navigate a service
46. a web page is not a resource
47. it is a (complete) representation of a resource
54. A FEW EXAMPLESLet’s Start With Proper URL Design
55. BAD URLS• http://www.acme.com/product/• http://www.acme.com/product/ﬁlter/cats/desc• http://www.acme.com/product/1234 WTF?• http://www.acme.com/photos/product/1234 new what?• http://www.acme.com/photos/product/1234/new sausage ID?• http://www.acme.com/photos/product/1234/5678
56. GOOD URLS a list of products• http://www.acme.com/products/ filtering is a query• http://www.acme.com/products/?ﬁlter=cats&sort=desc a single product• http://www.acme.com/products/1234 all photos• http://www.acme.com/products/1234/photos/• http://www.acme.com/products/1234/photos/?sort=latest• http://www.acme.com/products/1234/photos/5678
57. now heres the ironic part
58. URLs dont matter once you have a fully RESTful interface
59. but it helps to think in terms of resources
60. THE NEXT LEVELTime To Throw CRUD Into The Mix
61. COLLECTION OPERATIONS• http://www.acme.com/products/ • GET to retrieve a list of products • POST to create a new product • returns • 201 Created • Location: http://www.acme.com/products/1235
62. ITEM OPERATIONS• http://www.acme.com/products/1234 • GET to retrieve • PUT to update • DELETE to, you guessed it, delete
63. but please
64. dont let the server maintain client state (e.g. cookies)
65. Now we are at Level 2 in RMM
66. RMM LEVEL 2• Use HTTP verbs • GET (safe and idempotent) • POST (unsafe, not idempotent) • PUT & DELETE (unsafe, idempotent)• Use HTTP status codes to indicate result success • e.g. HTTP/1.1 409 Conﬂict
67. TWITTERS “REST” API, DISSECTED(well, not the whole API; just the status methods will do)
68. mind you were not even inspecting the RESTfulness
69. were just looking at Twitters API from an HTTP perspective
70. STATUSES/SHOW• GET http://api.twitter.com/1/statuses/show/id.format• Problems: • Operation (“show”) included in the URL • Status ID not a child of the “statuses” collection• Better: GET http://twitter.com/statuses/id with Accept header
71. STATUSES/UPDATE• POST http://api.twitter.com/1/statuses/update.format• Problems: • Operation (“update”) included in the URL • Uses the authenticated user implicitly• Better: POST http://twitter.com/users/id/statuses/
72. STATUSES/DESTROY• POST http://api.twitter.com/1/statuses/destroy/id.format• Problems: • Operation (“destroy”) included in the URL like it’s 1997 • Odd, illogical hierarchy again • Allows both “POST” and “DELETE” as verbs• Better: DELETE http://twitter.com/statuses/id
73. STATUSES/RETWEETS• GET http://api.twitter.com/1/statuses/retweets/id.format• Problems: • Hierarchy is wrong• Better: GET http://twitter.com/statuses/id/retweets/
74. STATUSES/RETWEET• PUT http://api.twitter.com/1/statuses/retweet/id.format• Problems: • “retweets” collection exists, but is not used here • As usual, the action is in the URL (“make retweet” is RPC-y) • Allows both “PUT” and “POST” as verbs• Better: POST http://twitter.com/statuses/id/retweets/
75. SUMMARY• http://twitter.com/statuses/ • POST to create a new tweet• http://twitter.com/statuses/12345 • DELETE deletes, PUT could be used for updates• http://twitter.com/statuses/12345/retweets • POST creates a new retweet
76. ANGRY GERMAN SUMMARY• Twitters "REST" API sucks, hates HTTP and kills baby kittens.
77. INTERMISSIONWhats the Biggest Reason for the Success of the Web?
79. ﬁrst data exchange system
80. planetary scale
81. why is that possible?
83. the web has no tight coupling
84. or a notiﬁcation infrastructure
85. that limits scalability
86. the web embraces failure
87. its loosely coupled by design
88. HTTP/1.1 404 Not Found
89. a link can die, others may still work
90. links are the exclusive mechanism to navigate the web
91. adding information to the web doesnt increase friction
92. (other than being able to ﬁnd it)
93. the WWW is the biggest application of the Internet because it is protocol-centric
94. VOLUME TWODesigning a RESTful Service
95. THE UNIFORM INTERFACE• Identiﬁcation of Resources (e.g. through URIs) • Representations are conceptually separate!• Manipulation Through Representations (i.e. they are complete)• Self-Descriptive Messages (containing all information)• Hypermedia As The Engine Of Application State ("HATEOAS") magic awesomesauce essential to REST
96. HATEOASThe Missing Piece in the Puzzle
97. ONE LAST PIECE IS MISSING• How does a client know what to do with resources?• How do you go to the “next” operation?• What are the URLs for creating subordinate resources?• Where is the contract for the service?
98. HYPERMEDIA AS THE ENGINE OF APPLICATION STATE• Use links to allow clients to discover locations and operations• Link relations are used to express the possible options• Clients do not need to know URLs, so they can change• The entire application workﬂow is abstracted, thus changeable• The hypermedia type itself could be versioned if necessary• No breaking of clients if the implementation is updated!
99. XHTML and Atom are Hypermedia formats
100. Or you roll your own...
101. A CUSTOM MEDIA TYPEGET  /products/1234  HTTP/1.1Host:  acme.comAccept:  application/vnd.acmecorpshop+xml Uniform Interface! re-use Atom forHTTP/1.1  200  OKContent-­‐Type:  application/vnd.acmecorpshop+xml;  charset=utf-­‐8 link relationsAllow:  GET,  PUT,  DELETE<?xml  version="1.0"  encoding="utf-­‐8"?><product  xmlns="urn:com.acme.prods"  xmlns:atom="http://www.w3.org/2005/xlink">    <id>1234</id>    <name>Red  Stapler</name>    <price  currency="EUR">3.14</price>    <atom:link  rel="payment"  type="application/vnd.acmecorpshop+xml"                          href="http://acme.com/products/1234/payment"/></product> meaning defined in Atom standard!
102. boom, RMM Level 3
103. XML is really good for hypermedia formats
104. (hyperlinks, namespaced attributes, re-use of formats, …)
105. JSON is more difﬁcult
106. (no hyperlinks, no namespaces, no element attributes)
121. does not yet use a custom media type, hope theyll ﬁx that
122. HOSTS AND VERSIONING• Q: Why not http://api.twitter.com/ ? • A: Because http://api.twitter.com/statuses/1234 and http:// twitter.com/statuses/1234 would be different resources!• Q: What about /1/ or /2/ for versioning? • A: Again, different resources. Instead, use the media type: application/vnd.com.twitter.api.v1+xml or application/vnd.com.twitter.api+xml;ver=2
123. YOU MIGHT BE WONDERING Why Exactly Is This Awesome?
124. THE MERITS OF REST• Easyto evolve: add new • Easyto implement: build it features or elements without on top of HTTP, and proﬁt! breaking BC • Authentication & TLS• Easy to learn: developers can "browse" service via link rels • Caching & Load Balancing• Easyto scale up: grows well • Conditional Requests with number of features, users and servers • Content Negotiation
126. hold on, you say
127. a plain HTTP-loving service does the job, you say
128. surely, there is a merit to REST beyond extensibility, you ask
130. "REST is software design on the scale of decades: everydetail is intended to promote software longevity andindependent evolution. Many of the constraints aredirectly opposed to short-term efﬁciency. Unfortunately,people are fairly good at short-term design, and usuallyawful at long-term design." Roy Fielding
131. "Most of RESTs constraints are focused on preservingindependent evolvability over time, which is onlymeasurable on the scale of years. Most developerssimply dont care what happens to their product yearsafter it is deployed, or at least they expect to be aroundto rewrite it when such change occurs." Roy Fielding
132. FURTHER READING• Ryan Tomayko How I Explained REST to my Wife http://tomayko.com/writings/rest-to-my-wife• Jim Webber, Savas Parastatidis & Ian Robinson How to GET a Cup of Coffee http://www.infoq.com/articles/webber-rest-workﬂow• Roy Thomas Fielding Architectural Styles and the Design of Network-based Software Architectures http://www.ics.uci.edu/~ﬁelding/pubs/dissertation/top.htm
133. BOOKS ON REST• Jim Webber, Savas Parastatidis, Ian Robinson REST in Practice ISBN: 978-0596805821• Subbu Allamaraju RESTful Web Services Cookbook ISBN: 978-0596801687• Leonard Richardson, Sam Ruby RESTful Web Services ISBN: 978-0596529260
134. !e End
136. THANK YOU! This was http://joind.in/3013 by @dzuelkeSend me questions or hire us:firstname.lastname@example.org