Presentation for BT Developer Day, 9 March 2010.

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