Doing REST Right

  • 37,867 views
Uploaded on

Presentation for BT Developer Day, 9 March 2010.

Presentation for BT Developer Day, 9 March 2010.

More in: Technology , Business
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
No Downloads

Views

Total Views
37,867
On Slideshare
0
From Embeds
0
Number of Embeds
28

Actions

Shares
Downloads
344
Comments
2
Likes
46

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

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