Doing REST Right
-
Upload
kerry-buckley -
Category
Technology
-
view
38.685 -
download
0
description
Transcript of Doing REST Right
![Page 1: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/1.jpg)
How to do RESTful web services right
Kerry Buckley & Paul Moser
BT DevCon2
9 March 2010
![Page 2: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/2.jpg)
How to do RESTful web services right
One way
![Page 3: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/3.jpg)
How to do RESTful web services right
(for some value of ‘right’)
One way
![Page 4: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/4.jpg)
What is REST?
REST is an architectural style, not a protocol or a standard. Hence many values of “right” (and much disagreement).
![Page 5: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/5.jpg)
‘A style of software architecture for
distributed hypermedia systems such as the World Wide Web’
Not necessarily HTTP, although in practice it generally is.
![Page 6: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/6.jpg)
Not SOAP
Seems to be a common (but wrong) definition.
![Page 7: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/7.jpg)
Constraints
![Page 8: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/8.jpg)
• Client-server
• Stateless
• Cacheable
• Layered system
• Uniform interface
![Page 9: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/9.jpg)
Principles
![Page 10: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/10.jpg)
• Identification of resources
• Manipulation of resources through these representations
• Self-descriptive messages
• Hypermedia as the engine of application state
![Page 11: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/11.jpg)
Goals
![Page 12: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/12.jpg)
• Scalability of component interactions
• Generality of interfaces
• Independent deployment of components
• Intermediary components to reduce latency, enforce security and encapsulate legacy systems
![Page 13: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/13.jpg)
Shop example
![Page 14: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/14.jpg)
• List products
• View a product
• Create an order for a number of products
• Cancel order
• Pay for order
![Page 15: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/15.jpg)
XML-RPC(URI-tunnelling)
![Page 16: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/16.jpg)
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
![Page 17: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/17.jpg)
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
![Page 18: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/18.jpg)
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
![Page 19: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/19.jpg)
POST /pay_order?order_id=42&card_number=1234…
def pay_order(order_id, card_number) { …}
Request maps onto method call.
![Page 20: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/20.jpg)
✓Easy to understand
✓Works well for simple procedure calls
✓Simple to implement
✓Interoperable
![Page 21: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/21.jpg)
✗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)
![Page 22: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/22.jpg)
✗ Identification of resources
✗ Manipulation of resources through these representations
✗ Self-descriptive messages
✗ Hypermedia as the engine of application state
But is it REST?
![Page 23: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/23.jpg)
POX(plain old XML)
![Page 24: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/24.jpg)
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.
![Page 25: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/25.jpg)
✓Simple to implement
✓Interoperable
✓Allows complex data structures
![Page 26: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/26.jpg)
✗Tightly coupled
✗No metadata
✗Doesn’t use web for robustness
✗Doesn’t use SOAP for robustness either
![Page 27: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/27.jpg)
✗ Identification of resources
✗ Manipulation of resources through these representations
✗ Self-descriptive messages
✗ Hypermedia as the engine of application state
But is it REST?
![Page 28: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/28.jpg)
CRUD
![Page 29: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/29.jpg)
GET /products
GET /products/123
POST /orders
PUT /orders/42
DELETE /orders/42
POST /orders/42/payment
![Page 30: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/30.jpg)
Representations• Hypermedia
- XHTML
- Atom
- Custom XML schema
• Non-hypermedia
- Generic XML
- YAML
- JSON
- CSV
- etc
![Page 31: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/31.jpg)
✓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.
![Page 32: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/32.jpg)
✗ Ignores hypermedia
✗Tight coupling through URI templates
✗Not self-describing
![Page 33: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/33.jpg)
✓ Identification of resources
✓Manipulation of resources through these representations
✗ Self-descriptive messages
✗ Hypermedia as the engine of application state
But is it REST?
![Page 34: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/34.jpg)
REST
![Page 35: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/35.jpg)
API rootRequest
GET /
![Page 36: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/36.jpg)
API rootResponse
200 OKContent-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.
![Page 37: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/37.jpg)
View productsRequest
Get /products
Following the link with a relation of ‘products’ (link rel="products").
![Page 38: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/38.jpg)
View productsResponse
200 OKContent-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).
![Page 39: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/39.jpg)
View ordersRequest
Get /orders
![Page 40: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/40.jpg)
View ordersResponse
200 OKContent-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.
![Page 41: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/41.jpg)
Place orderRequest
POST /ordersContent-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.
![Page 42: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/42.jpg)
Place orderResponse
201 CreatedContent-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).
![Page 43: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/43.jpg)
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
![Page 44: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/44.jpg)
✓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.
![Page 45: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/45.jpg)
✗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.
![Page 46: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/46.jpg)
✓ Identification of resources
✓ Manipulation of resources through these representations
✓ Self-descriptive messages
✓ Hypermedia as the engine of application state
But is it REST?
![Page 47: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/47.jpg)
This is not the One True Way
As mentioned before, REST is just an architectural style. There are other approaches to creating RESTful APIs.
![Page 48: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/48.jpg)
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
![Page 49: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/49.jpg)
Using HTTP features
![Page 50: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/50.jpg)
Response codes• 200 OK
• 201 Created
• 202 Accepted
• 204 No content
• 301 Moved permanently
• 400 Bad request
• 403 Forbidden
• 404 Not found
• 405 Method not allowed
• 409 Conflict
• 410 Gone
• etc
![Page 51: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/51.jpg)
Restricting transitions
Request Response
OPTIONS /orders/123(an open order)
200 OKAllow: GET, PUT, DELETE
OPTIONS /orders/42(a despatched order)
200 OKAllow: GET
![Page 52: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/52.jpg)
Restricting transitions
Request Response
DELETE /orders/123Expect: 100-Continue
100 Continue
DELETE /orders/42Expect: 100-Continue
417 Expectation Failed
![Page 53: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/53.jpg)
Prevent race conditions
Request
PUT /orders/123If-Unmodified-Since: Tue, 9 Mar 2010 11:00:00 GMT
Response
200 OK
or
412 Precondition Failed
![Page 54: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/54.jpg)
Prevent race conditions
Request
GET /orders/123
Response (partial)
200 OKETag: 686897696a7c876b7e
Request
PUT /orders/123If-Match: 686897696a7c876b7e
![Page 55: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/55.jpg)
Security
• HTTP basic
• HTTP digest
• Shared secret (OAuth etc)
• SSL
• Selective encryption
![Page 56: Doing REST Right](https://reader038.fdocuments.us/reader038/viewer/2022103114/554fb1cab4c90586258b51ba/html5/thumbnails/56.jpg)
More
• Jim Webber tutorial
http://tinyurl.com/rest-tutorial
• Restfulie framework (Rails & Java):
http://tinyurl.com/restfulie