Your SlideShare is downloading. ×
0
How to do RESTful
web services right
   Kerry Buckley & Paul Moser

         BT DevCon2

         9 March 2010
w ay
 ne
O How to do RESTful
   web services right
w ay
 ne
O How to do RESTful
   web services right
     (for some value of ‘right’)
What is REST?



REST is an architectural style, not a protocol or a standard. Hence many values of “right” (and
much disa...
‘A style of software
              architecture for
          distributed hypermedia
            systems such as the
     ...
Not SOAP



Seems to be a common (but wrong) definition.
Constraints
• Client-server
• Stateless
• Cacheable
• Layered system
• Uniform interface
Principles
• Identification of resources
• Manipulation of resources through these
  representations

• Self-descriptive messages
• Hy...
Goals
• Scalability of component interactions
• Generality of interfaces
• Independent deployment of components
• Intermediary c...
Shop example
• List products
• View a product
• Create an order for a number of products
• Cancel order
• Pay for order
XML-RPC
(URI-tunnelling)
GET /api?action=list_products

      GET /api?action=view_product&product_id=123

      GET /api?action=create_order&produ...
GET /list_products

     GET /view_product?product_id=123

     GET /create_order?product_id=123&product_id=456…

     GET...
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…

      def pay_order(order_id, card_number) {
        …
      }




Request ...
✓Easy to understand
✓Works well for simple procedure calls
✓Simple to implement
✓Interoperable
✗ Brittle
          ✗ Tightly coupled
          ✗ Failure cases require manual handling
          ✗ No metadata


Need to ...
But is it REST?
✗ Identification of resources
✗ Manipulation of resources through these
   representations
✗ Self-descripti...
POX
(plain old XML)
Request

     POST /create_order

     <create_order_request>
      <line>
        <product_id>123</product_line>
        ...
✓Simple to implement
✓Interoperable
✓Allows complex data structures
✗ Tightly coupled
✗ No metadata
✗ Doesn’t use web for robustness
✗ Doesn’t use SOAP for robustness either
But is it REST?
✗ Identification of resources
✗ Manipulation of resources through these
   representations
✗ Self-descripti...
CRUD
GET /products

GET /products/123

POST /orders

PUT /orders/42

DELETE /orders/42

POST /orders/42/payment
Representations
•   Hypermedia              •   Non-hypermedia

    -   XHTML                   -   Generic XML

    -   A...
✓Makes good use of HTTP
          ✓Uniform interface
          ✓Good for database-style applications


Because each resour...
✗ Ignores hypermedia
✗ Tight coupling through URI templates
✗ Not self-describing
But is it REST?
✓ Identification of resources
✓ Manipulation of resources through these
   representations
✗ Self-descripti...
REST
API root
Request

GET /
API root
            Response

            200 OK
            Content-Type: application/vnd.rest-example.store+xml

      ...
View products
             Request

             Get /products




Following the link with a relation of ‘products’ (link ...
View products
             Response

             200 OK
             Content-Type: application/vnd.rest-example.products+...
View orders
Request

Get /orders
View orders
            Response

            200 OK
            Content-Type: application/vnd.rest-example.orders+xml

  ...
Place order
            Request

            POST /orders
            Content-Type: application/vnd.rest-example.order+xml...
Place order
            Response

            201 Created
            Content-Type: application/vnd.rest-example.order+xml...
Clients only need know

• The root URI (‘home page’) of the API
• Definitions for the media types used
 - eg schemas or exa...
✓Makes full use of HTTP
           ✓Self-describing
           ✓Loosely coupled


Only need to know entry URI and media ty...
✗ More complex to implement
          ✗ Transition links can lead back to RPC-style



Frameworks help. Tempting to just a...
But is it REST?
✓ Identification of resources
✓ Manipulation of resources through these
   representations
✓ Self-descripti...
This is not the One
                    True Way


As mentioned before, REST is just an architectural style. There are oth...
An alternative:
‘Web site is your API’
• No separation between web site and API
• Representations are HTML
• Data submitte...
Using HTTP features
Response codes
•   200 OK                  •   400 Bad request

•   201 Created             •   403 Forbidden

•   202 Acc...
Restricting transitions
      Request                 Response


OPTIONS /orders/123             200 OK
   (an open order)...
Restricting transitions
      Request                Response


DELETE /orders/123
                           100 Continue...
Prevent race conditions
 Request
 PUT /orders/123
 If-Unmodified-Since: Tue, 9 Mar 2010 11:00:00 GMT
 Response
 200 OK
 or
...
Prevent race conditions
 Request
 GET /orders/123
 Response (partial)
 200 OK
 ETag: 686897696a7c876b7e
 Request
 PUT /ord...
Security

• HTTP basic
• HTTP digest
• Shared secret (OAuth etc)
• SSL
• Selective encryption
More

• Jim Webber tutorial
      http://tinyurl.com/rest-tutorial
• Restfulie framework (Rails & Java):
      http://tiny...
Upcoming SlideShare
Loading in...5
×

Doing REST Right

39,100

Published on

Presentation for BT Developer Day, 9 March 2010.

Published in: Technology, Business
2 Comments
50 Likes
Statistics
Notes
No Downloads
Views
Total Views
39,100
On Slideshare
0
From Embeds
0
Number of Embeds
28
Actions
Shares
0
Downloads
357
Comments
2
Likes
50
Embeds 0
No embeds

No notes for slide

Transcript of "Doing REST Right"

  1. 1. How to do RESTful web services right Kerry Buckley & Paul Moser BT DevCon2 9 March 2010
  2. 2. w ay ne O How to do RESTful web services right
  3. 3. w ay ne O How to do RESTful web services right (for some value of ‘right’)
  4. 4. What is REST? REST is an architectural style, not a protocol or a standard. Hence many values of “right” (and much disagreement).
  5. 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. 6. Not SOAP Seems to be a common (but wrong) definition.
  7. 7. Constraints
  8. 8. • Client-server • Stateless • Cacheable • Layered system • Uniform interface
  9. 9. Principles
  10. 10. • Identification of resources • Manipulation of resources through these representations • Self-descriptive messages • Hypermedia as the engine of application state
  11. 11. Goals
  12. 12. • Scalability of component interactions • Generality of interfaces • Independent deployment of components • Intermediary components to reduce latency, enforce security and encapsulate legacy systems
  13. 13. Shop example
  14. 14. • List products • View a product • Create an order for a number of products • Cancel order • Pay for order
  15. 15. XML-RPC (URI-tunnelling)
  16. 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. 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. 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. 19. POST /pay_order?order_id=42&card_number=1234… def pay_order(order_id, card_number) { … } Request maps onto method call.
  20. 20. ✓Easy to understand ✓Works well for simple procedure calls ✓Simple to implement ✓Interoperable
  21. 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. 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. 23. POX (plain old XML)
  24. 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. 25. ✓Simple to implement ✓Interoperable ✓Allows complex data structures
  26. 26. ✗ Tightly coupled ✗ No metadata ✗ Doesn’t use web for robustness ✗ Doesn’t use SOAP for robustness either
  27. 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. 28. CRUD
  29. 29. GET /products GET /products/123 POST /orders PUT /orders/42 DELETE /orders/42 POST /orders/42/payment
  30. 30. Representations • Hypermedia • Non-hypermedia - XHTML - Generic XML - Atom - YAML - Custom XML schema - JSON - CSV - etc
  31. 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. 32. ✗ Ignores hypermedia ✗ Tight coupling through URI templates ✗ Not self-describing
  33. 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. 34. REST
  35. 35. API root Request GET /
  36. 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. 37. View products Request Get /products Following the link with a relation of ‘products’ (link rel="products").
  38. 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. 39. View orders Request Get /orders
  40. 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. 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. 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. 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. 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. 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. 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. 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. 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. 49. Using HTTP features
  50. 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. 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. 52. Restricting transitions Request Response DELETE /orders/123 100 Continue Expect: 100-Continue DELETE /orders/42 417 Expectation Failed Expect: 100-Continue
  53. 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. 54. Prevent race conditions Request GET /orders/123 Response (partial) 200 OK ETag: 686897696a7c876b7e Request PUT /orders/123 If-Match: 686897696a7c876b7e
  55. 55. Security • HTTP basic • HTTP digest • Shared secret (OAuth etc) • SSL • Selective encryption
  56. 56. More • Jim Webber tutorial http://tinyurl.com/rest-tutorial • Restfulie framework (Rails & Java): http://tinyurl.com/restfulie
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×