Doing REST Right
Upcoming SlideShare
Loading in...5
×
 

Like this? Share it with your network

Share

Doing REST Right

on

  • 27,253 views

Presentation for BT Developer Day, 9 March 2010.

Presentation for BT Developer Day, 9 March 2010.

Statistics

Views

Total Views
27,253
Views on SlideShare
25,461
Embed Views
1,792

Actions

Likes
44
Downloads
337
Comments
2

48 Embeds 1,792

http://chamnap.github.com 483
http://chamnapchhorn.blogspot.com 427
http://www.scoop.it 417
http://ddiupbblogs.wordpress.com 159
http://chamnapchhorn.blogspot.in 71
http://chamnapchhorn.blogspot.de 35
https://twimg0-a.akamaihd.net 20
http://localhost:4000 20
http://chamnapchhorn.blogspot.co.uk 19
http://chamnapchhorn.blogspot.fr 15
http://chamnapchhorn.blogspot.dk 12
http://chamnapchhorn.blogspot.ca 10
http://chamnapchhorn.blogspot.jp 7
https://si0.twimg.com 6
http://confluence 6
http://a0.twimg.com 6
http://chamnapchhorn.blogspot.ru 5
http://www.slideshare.net 5
http://chamnapchhorn.blogspot.com.es 4
http://chamnapchhorn.blogspot.com.br 4
http://chamnapchhorn.blogspot.co.il 4
http://chamnap.github.io 4
http://www.linkedin.com 4
http://feeds2.feedburner.com 4
http://chamnapchhorn.blogspot.com.tr 3
http://chamnapchhorn.blogspot.kr 3
http://www.chamnapchhorn.blogspot.de 3
http://chamnapchhorn.blogspot.sg 3
https://twitter.com 3
http://chamnapchhorn.blogspot.nl 3
http://us-w1.rockmelt.com 3
http://www.chamnapchhorn.blogspot.com 3
http://chamnapchhorn.blogspot.ch 2
http://chamnapchhorn.blogspot.ie 2
http://chamnapchhorn.blogspot.co.at 2
http://webcache.googleusercontent.com 2
http://chamnapchhorn.blogspot.hk 2
http://www.redditmedia.com 1
http://chamnapchhorn.blogspot.co.nz 1
http://chamnapchhorn.blogspot.ro 1
http://feeds.feedburner.com 1
http://www.twylah.com 1
http://chamnapchhorn.blogspot.sk 1
http://ops42.wordpress.com 1
http://chamnapchhorn.blogspot.tw 1
http://chamnapchhorn.blogspot.se 1
http://chamnapchhorn.blogspot.gr 1
http://chamnapchhorn.blogspot.it 1
More...

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Doing REST Right Presentation Transcript

  • 1. How to do RESTful web services right Kerry Buckley & Paul Moser BT DevCon2 9 March 2010
  • 2. w ay ne O How to do RESTful web services right
  • 3. w ay ne O How to do RESTful web services right (for some value of ‘right’)
  • 4. What is REST? REST is an architectural style, not a protocol or a standard. Hence many values of “right” (and much disagreement).
  • 5. ‘A style of software architecture for distributed hypermedia systems such as the World Wide Web’ Not necessarily HTTP, although in practice it generally is.
  • 6. Not SOAP Seems to be a common (but wrong) definition.
  • 7. Constraints
  • 8. • Client-server • Stateless • Cacheable • Layered system • Uniform interface
  • 9. Principles
  • 10. • Identification of resources • Manipulation of resources through these representations • Self-descriptive messages • Hypermedia as the engine of application state
  • 11. Goals
  • 12. • Scalability of component interactions • Generality of interfaces • Independent deployment of components • Intermediary components to reduce latency, enforce security and encapsulate legacy systems
  • 13. Shop example
  • 14. • List products • View a product • Create an order for a number of products • Cancel order • Pay for order
  • 15. XML-RPC (URI-tunnelling)
  • 16. GET /api?action=list_products GET /api?action=view_product&product_id=123 GET /api?action=create_order&product_id=123&product_id=456… GET/api?action=pay_order&order_id=42&card_number=1234… Sometimes only a single ‘endpoint’ URI
  • 17. GET /list_products GET /view_product?product_id=123 GET /create_order?product_id=123&product_id=456… GET/pay_order?order_id=42&card_number=1234… Or one endpoint per method
  • 18. GET /list_products GET /view_product?product_id=123 POST /create_order?product_id=123&product_id=456… POST /pay_order?order_id=42&card_number=1234… Marginally better without unsafe GETs
  • 19. POST /pay_order?order_id=42&card_number=1234… def pay_order(order_id, card_number) { … } Request maps onto method call.
  • 20. ✓Easy to understand ✓Works well for simple procedure calls ✓Simple to implement ✓Interoperable
  • 21. ✗ Brittle ✗ Tightly coupled ✗ Failure cases require manual handling ✗ No metadata Need to know all the URIs, methods and parameters in advance (out-of-band documentation)
  • 22. But is it REST? ✗ Identification of resources ✗ Manipulation of resources through these representations ✗ Self-descriptive messages ✗ Hypermedia as the engine of application state
  • 23. POX (plain old XML)
  • 24. Request POST /create_order <create_order_request> <line> <product_id>123</product_line> <quantity>1</quantity> </line> … </create_order_request> Response 200 OK <create_order_response> <status>OK</status> <order_id>42</order_id> </create_order_response> Both request and response have XML bodies.
  • 25. ✓Simple to implement ✓Interoperable ✓Allows complex data structures
  • 26. ✗ Tightly coupled ✗ No metadata ✗ Doesn’t use web for robustness ✗ Doesn’t use SOAP for robustness either
  • 27. But is it REST? ✗ Identification of resources ✗ Manipulation of resources through these representations ✗ Self-descriptive messages ✗ Hypermedia as the engine of application state
  • 28. CRUD
  • 29. GET /products GET /products/123 POST /orders PUT /orders/42 DELETE /orders/42 POST /orders/42/payment
  • 30. Representations • Hypermedia • Non-hypermedia - XHTML - Generic XML - Atom - YAML - Custom XML schema - JSON - CSV - etc
  • 31. ✓Makes good use of HTTP ✓Uniform interface ✓Good for database-style applications Because each resource has a URI you can use caching etc. Uniform interface: verbs are GET, POST, PUT and DELETE.
  • 32. ✗ Ignores hypermedia ✗ Tight coupling through URI templates ✗ Not self-describing
  • 33. But is it REST? ✓ Identification of resources ✓ Manipulation of resources through these representations ✗ Self-descriptive messages ✗ Hypermedia as the engine of application state
  • 34. REST
  • 35. API root Request GET /
  • 36. API root Response 200 OK Content-Type: application/vnd.rest-example.store+xml <store> <link method="get" rel="products" href="http://rest-demo.local/products"/> <link method="get" rel="orders" href="http://rest-demo.local/orders"/> </store> Links contain information on what we can do.
  • 37. View products Request Get /products Following the link with a relation of ‘products’ (link rel="products").
  • 38. View products Response 200 OK Content-Type: application/vnd.rest-example.products+xml <products> <link method="get" rel="latest" href="http://rest-demo.local/products"/> <product> <link method="get" rel="view" href="http://rest-demo.local/products/1"/> <code>A-001</code> <description>Tartan Paint</description> <price>4.95</price> </product> … </products> Note link to retrieve the latest version of this resource (eg if you had it cached).
  • 39. View orders Request Get /orders
  • 40. View orders Response 200 OK Content-Type: application/vnd.rest-example.orders+xml <orders> <link method="get" rel="latest" href="http://rest-demo.local/orders"/> <link type="application/vnd.rest-example.order+xml" method="post" rel="new" href="http://rest-demo.local/orders"/> </orders> No orders yet, but note link to create a new one.
  • 41. Place order Request POST /orders Content-Type: application/vnd.rest-example.order+xml <order> <line> <product>http://rest-demo.local/products/1</product> <quantity>2</quantity> </line> </order> Again following a link, this time posting data of the specified type.
  • 42. Place order Response 201 Created Content-Type: application/vnd.rest-example.order+xml <order> <link method="get" rel="latest" href="http://rest-demo.local/orders/9"/> <link method="delete" rel="cancel" href="http://rest-demo.local/orders/9"/> <link type="application/vnd.rest-example.payment-details+xml" method="post" rel="pay" href="http://rest-demo.local/orders/9/pay"/> <line> <product>http://rest-demo.local/products/1</product> <quantity>2</quantity> <cost>9.90</cost> </line> <total>9.90</total> </order> Note links to cancel or pay for the order – HATEOAS! The links included would depend on the allowable state transitions (eg no cancel link for a despatched order).
  • 43. Clients only need know • The root URI (‘home page’) of the API • Definitions for the media types used - eg schemas or example documents • Everything else is just HTTP and links
  • 44. ✓Makes full use of HTTP ✓Self-describing ✓Loosely coupled Only need to know entry URI and media types – API can be explored using links. If link URIs change, well-behaved clients should not break.
  • 45. ✗ More complex to implement ✗ Transition links can lead back to RPC-style Frameworks help. Tempting to just add a bunch of actions as links, using overloaded post.
  • 46. But is it REST? ✓ Identification of resources ✓ Manipulation of resources through these representations ✓ Self-descriptive messages ✓ Hypermedia as the engine of application state
  • 47. This is not the One True Way As mentioned before, REST is just an architectural style. There are other approaches to creating RESTful APIs.
  • 48. An alternative: ‘Web site is your API’ • No separation between web site and API • Representations are HTML • Data submitted using HTML forms • Semantics via microformats
  • 49. Using HTTP features
  • 50. Response codes • 200 OK • 400 Bad request • 201 Created • 403 Forbidden • 202 Accepted • 404 Not found • 204 No content • 405 Method not allowed • 301 Moved permanently • 409 Conflict • 410 Gone • etc
  • 51. Restricting transitions Request Response OPTIONS /orders/123 200 OK (an open order) Allow: GET, PUT, DELETE OPTIONS /orders/42 200 OK (a despatched order) Allow: GET
  • 52. Restricting transitions Request Response DELETE /orders/123 100 Continue Expect: 100-Continue DELETE /orders/42 417 Expectation Failed Expect: 100-Continue
  • 53. Prevent race conditions Request PUT /orders/123 If-Unmodified-Since: Tue, 9 Mar 2010 11:00:00 GMT Response 200 OK or 412 Precondition Failed
  • 54. Prevent race conditions Request GET /orders/123 Response (partial) 200 OK ETag: 686897696a7c876b7e Request PUT /orders/123 If-Match: 686897696a7c876b7e
  • 55. Security • HTTP basic • HTTP digest • Shared secret (OAuth etc) • SSL • Selective encryption
  • 56. More • Jim Webber tutorial http://tinyurl.com/rest-tutorial • Restfulie framework (Rails & Java): http://tinyurl.com/restfulie