Recommandé
Recommandé
Contenu connexe
Tendances
Tendances (20)
Similaire à Doing REST Right
Similaire à Doing REST Right (20)
Plus de Kerry Buckley
Plus de Kerry Buckley (20)
Dernier
Dernier (20)
Doing REST Right
- 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
- 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
- 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
- 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).
- 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
- 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