1. REST in Practice COMP6017 Topics on Web Services Dr Nicholas Gibbins – nmg@ecs.soton.ac.uk 2012-2013

2. Scenario: Orinoco Books 2 Online bookseller with simple workflow: –Customer adds items to virtual shopping cart –Checkout and payment –Order shipped order open payment received order cancelled preparing order shipped update cart cancel pay add to queue check status deliver create order

3. Model of RESTful maturity REST constraints made concrete, in context of Web technology stack HypermediaHTTPURI Richardson Maturity Model 3

4. Richardson Level 1 4

5. Multiple URIs used for resources Key resource type from the workflow is an order –http://orinoco.com/order/{order_id}

6. Richardson Level 2 6

7. We have different URIs for each order (resource) How do we interact with the orders? –create a new order –add items to an order –remove items from an order –cancel an order –checkout and payment (submit order) –check order status Use appropriate HTTP methods!

8. Create an order 8 Can use either PUT or POST PUT to a new URI –new URI: http://orinoco.com/order/{order_id} –client chooses order id POST to an existing URI –existing URI: http://orinoco.com/order/ –server chooses order id

9. PUT 9 PUT /order/1234 HTTP/1.1 Host: orinoco.com Content-Type: application/xml Content-Length: 107 HTTP/1.1 200 OK Date: Tue, 13 Nov 2012 09:30:00 GMT Content-Length: 0

10. POST 10 PUT /order/ HTTP/1.1 Host: orinoco.com Content-Type: application/xml Content-Length: 107 HTTP/1.1 201 Created Location: /order/1234 Date: Tue, 13 Nov 2012 09:30:00 GMT

11. Add/Remove items 11 Use PUT with existing order URI

12. PUT 12 PUT /order/1234 HTTP/1.1 Host: orinoco.com Content-Type: application/xml Content-Length: 134 HTTP/1.1 200 OK Date: Tue, 13 Nov 2012 09:30:00 GMT Content-Length: 0

13. PUT 13 Use If-Unmodified-Since header to check whether the resource has been changed (by a third party)

14. PUT 14 PUT /order/1234 HTTP/1.1 Host: orinoco.com Content-Type: application/xml Content-Length: 134 If-Unmodified-Since: Tue, 13 Nov 2012 09:30:00 GMT HTTP/1.1 412 Precondition Failed Date: Tue, 13 Nov 2012 09:35:00 GMT Content-Length: 0

15. Cancel an order 15 Use DELETE DELETE is idempotent –repeated DELETEs have the same effect as a single DELETE

16. DELETE 16 DELETE /order/1234 HTTP/1.1 Host: orinoco.com HTTP/1.1 200 OK Content-Length: 0 Date: Tue, 13 Nov 2012 09:30:00 GMT

17. DELETE 17 DELETE /order/1234 HTTP/1.1 Host: orinoco.com HTTP/1.1 404 Not Found Content-Length: 0 Date: Tue, 13 Nov 2012 09:30:00 GMT

18. DELETE 18 DELETE /order/1234 HTTP/1.1 Host: orinoco.com HTTP/1.1 409 Conflict Content-Length: 0 Date: Tue, 13 Nov 2012 09:30:00 GMT

19. Check Order Status 19 Use GET –GET is idempotent –GET has no side-effects!

20. GET 20 GET /order/1234 HTTP/1.1 Host: orinoco.com HTTP/1.1 200 OK Content-Type: application/xml Content-Length: 107 Date: Tue, 13 Nov 2012 09:30:00 GMT open

21. GET 21 GET /order/9999 HTTP/1.1 Host: orinoco.com HTTP/1.1 404 Not Found Content-Type: application/xml Content-Length: 0 Date: Tue, 13 Nov 2012 09:30:00 GMT

22. Collections and Elements 22 Extra conventions for talking about collections of elements –An order is a collection –An item in the order is an element of a collection Some consensus of semantics of HTTP methods for these In our case: –http://orinoco.com/order/ is a collection –http://orinoco.com/order/{order_id} is an element

23. RESTful Methods for Collections 23 MethodBehaviour GETList the members of the collection (list of URIs) PUTReplace the entire collection with another collection POSTCreate a new member in the collection and automatically assign it a URI DELETEDelete the entire collection

24. RESTful Methods for Collection Elements 24 MethodBehaviour GETRetrieve a representation of the specified element PUTReplace the specified element of the collection, or if it doesn’t exist create it POSTTreat the specified member as a collection and create a new element in it DELETEDelete the specified member of the collection

25. CRUD isn’t everything 25 Limited application model –In our scenario, payment doesn’t fit in cleanly –Encourages tight coupling through URI templates –Simple pattern –Ignores hypermedia!

26. Richardson Level 3 26

27. Where are the links? open What can you do next?

28. Media Types 28 application/xml doesn’t have specific link semantics Can adopt standard hypermedia format (XHTML, Atom, etc) –Widely understood by software agents –Needs to be adapted to domain Can create domain-specific format that supports application –Direct supports domain –Maintains visibility of messages at the protocol level –Not widely understood Use link types to define protocols

29. application/xhtml+xml 29 1234567890 1 payment

30. application/xhtml+xml 30 Use OPTIONS to ascertain the right HTTP method to use with links –Allow: header in response lists allowed methods –For payment, PUT? Need to define link types for use with rel –Microformats, RDF, etc

31. application/vnd.orinoco+xml 31 Proprietary (vendor-specific) media type –Uses POX for business data –Uses (eg) Atom link elements for hypermedia control

32. application/vnd.orinoco+xml 32 open

33. Further Reading 33

34. Further Reading REST in Practice tutorial slides –http://www.slideshare.net/guilhermecaelum/rest-in-practice