Representational State Transfer (REST) and HATEOAS Service-Oriented Architecture Computing + Mathematical Sciences Auckland University of Technology Image used under Creative Commons from apasciuto http://flickr.com/apasciuto/ 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Outline 1 REST APIs Identification of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags & Optimistic Locking 5 REST Examples Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 2/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Outline 1 REST APIs Identification of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags & Optimistic Locking 5 REST Examples Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 3/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Warning before we start! REST != MVC Do not think in controllers, IDs, actions, models, views, plugins, helpers . . . In fact, do not think about implementation at all! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 4/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples What is REST? Roy Fielding, “Father” of REST REST is a coordinated set of architectural constraints that attempts to minimize latency and network communication while at the same time maximizing the independence and scalability of component implementations. This is achieved by placing constraints on connector semantics where other styles have focused on component semantics. REST enables the caching and reuse of interactions, dynamic substitutability of components, and processing of actions by intermediaries, thereby meeting the needs of an Internet-scale distributed hypermedia system. Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 5/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples What is REST?  REST is not a standard  REST is not a protocol REST is an architectural style for networked applications REST defines a set of simple principles (loosely followed by most API implementations) Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 6/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples What is REST? Advantages of REST Cacheable Stateless Scalable Fault-tolerant Loosely coupled Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 7/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples What is REST? Principles of REST URL identifies a resource URLs have a hierarchy Methods perform operations on resources Operation must be implicit Hypermedia format to represent data Link relations to navigate Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 8/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples What is REST? The Four Main Principles 1 Identification of resources 2 Manipulation of resources 3 Self-descriptive messages 4 HATEOAS Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 9/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Identification of Resources You are doing it wrong . . . :-( /index.php?action=getarticle&id=5 /default/article/5/4/6/size Cacheable? Scalable? Readable? Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 10/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Identification of Resources Readable and Maintainable! /articles We want all articles /articles/5/photos/4/comments/1 We want the first comment of the fourth photo for the fifth article /articles/5/photos/4/comments We want all comments of the fourth photo for the fifth article Cacheable!  Scalable!  Readable!  Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 11/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Identification of Resources Filtering through a Query String, not the URI  /photos/order/size/limit/5  /photos/limit/5/order/size  /photos?order=size&limit=5  /photos?limit=5&order=size Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 12/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Manipulation of Resources Create Retrieve Update Delete But please note: REST != CRUD Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 13/84 

No content

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Manipulation of Resources CRUD to HTTP verb mapping Create = POST Retrieve = GET Update = PUT (or PATCH) Delete = DELETE Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 15/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Manipulation of Resources Creating a Resource POST creates a new resource But the server decides on that resources URI Examples WWW: Posting to Web log → Server decides URI of posting and any comments made on that post Programmatic service: Creating a new employee record Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 16/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Manipulation of Resources Safe Methods Any client should be able to make the request . . . as many times as necessary GET, OPTIONS, HEAD Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 17/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Manipulation of Resources Idempotent Methods Guarantees that the client can repeat the request when it’s not certain x++ vs. x=4 All methods except “POST” Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 18/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages Stateless! All information for processing is available: How? (method + content-type) What? (URI) When? (preconditions) Who? (authentication) Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 19/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages How: Method GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth oauth_nonce="123" ... If-None-Matched: absad12412414 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 20/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages How: Content-Type GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth oauth_nonce="123" ... If-None-Matched: absad12412414 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 21/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages How: Content-Type application/vnd.mycompany.myapp-v1+json??? The vnd name space is for proprietary media types (as opposed to the IANA registered ones) We want to “talk” JSON, not XML or others We wnat to “play” with API version 1.0 (not any other) General notes: Interpret requests generously Be strict with responses Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 22/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages What GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth oauth_nonce="123" ... If-None-Matched: absad12412414 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 23/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages When GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth oauth_nonce="123" ... If-None-Matched: absad12412414 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 24/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages Who GET /article/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth oauth_nonce="123" ... If-None-Matched: absad12412414 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 25/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages? Encoding Google Trends chart: “XML API vs JSON API” (http://ur1.ca/ey5o6) JSON feels more self-descriptive, too . . . Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 26/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Self-Descriptive Messages WADL? We can describe RESTful XML Web Services (similar to WSDL) Web Application Description Language (WADL) (another XML grammar to describe HTTP-based web applications) But we don’t need a static contract description → We want self-descriptive messages, dammit! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 27/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples HATEOAS HATEOAS to the rescue! HATEOAS = Hypermedia As The Engine Of Application State → Magic awesome sauce to improve REST! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 28/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples HATEOAS This is the hardest and of course, most important part of REST . . . But it makes the API “explorable”! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 29/84 

Image used under Creative Commons from oliverkendal http://flickr.com/oliverkendal/ 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Links Use links to allow clients to discover locations and operations Link relations are used to express options Clients do not need to know URLs This controls the state Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 31/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Links Links contain (adapted from Atom format’s link definition): The target (href, mandatory) A short relationship indication (rel, mandatory) (e. g. “details”, “payment”, “cancel”) The content type needed for the request (type, optional) The HTTP method (method, optional) See also: http://www.subbu.org/blog/2008/10/generalized-linking Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 32/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Outline 1 REST APIs Identification of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags & Optimistic Locking 5 REST Examples Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 33/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Flight Booking API State inside your REST API The HATEOAS links indicate state transitions Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 34/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Search for Specified Flights POST /search?order=price&limit=5 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json { "destination": "LAX", "date": "2013-09-24", "type": "firstclass" } Note: This is an operation on a non-CRUD controller resource Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 35/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Returns a Collection of Flights HTTP/1.1 200 OK Content-type: application/vnd.mycompany.myapp-v1.0+json { "flights": [ { "flightno": "NZ1234", "time": "4:20", "links": [ { "href": "/flight/15263", "method": "GET", "rel": "details", "type": "application/vnd.mycompany.myapp+json" }, { "href": "/booking", "method": "POST", "rel": "confirm", "type": "application/vnd.mycompany.myapp+json" }, ] }, { "flightno": "EH123", "time": "3:55", "links": [ { "href": "/flight/523525, "method": "GET", "rel": "details", "type": "application/vnd.mycompany.myapp+json" }, { "href": "/booking", "method": "POST", "rel": "confirm", "type": "application/vnd.mycompany.myapp+json" }, ] } ] } Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 36/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Returns a Collection of Flights HTTP/1.1 200 OK Content-type: application/vnd.mycompany.myapp-v1.0+json { "flights": [ { "flightno": "NZ1234", "time": "4:20", "links": [ { "href": "/flight/15263", "method": "GET", "rel": "details", "type": "application/vnd.mycompany.myapp+json" }, { "href": "/booking", "method": "POST", "rel": "confirm", "type": "application/vnd.mycompany.myapp+json" }, ] }, { "flightno": "EH123", "time": "3:55", "links": [ { "href": "/flight/523525, "method": "GET", "rel": "details", "type": "application/vnd.mycompany.myapp+json" }, { "href": "/booking", "method": "POST", "rel": "confirm", "type": "application/vnd.mycompany.myapp+json" }, ] } ] } Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 37/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Confirm a Specific Flight POST /booking HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json { "flight": "/flight/15263", "seat": "42A", "meal": "vegetarian" } HTTP/1.1 401 Authentication required Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 38/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Confirm a Specific Flight . . . with more info POST /booking HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth ... { "flight": "/flight/15263", "seat": "42A", "meal": "vegetarian" } HTTP/1.1 201 Created Location: /booking/1616163 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 39/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples What can we do with our booking? OPTIONS /booking/1616163 HTTP/1.1 Host: www.mycompany.co.nz Authorization: OAuth ... HTTP/1.1 200 OK Allow: GET, PUT, DELETE Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 40/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Cancel our booking! DELETE /booking/1616163 HTTP/1.1 Host: www.mycompany.co.nz Authorization: OAuth ... HTTP/1.1 204 No content Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 41/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Still need to Pay for the Flight GET /booking/1616163 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth ... HTTP/1.1 200 OK Content-type: application/vnd.mycompany.myapp-v1.0+json { "flight": { "flightno": "NZ1234", "time": "4:20", "links": [ { "href": "/flight/15263", "method": "GET", "rel": "details", "type": "application/vnd.mycompany.myapp+json" } ] }, "payment": { "status": "Not paid", "links": [ { "href": "/payment/booking/1616163", "method": "GET", "rel": "details", "type": "application/vnd.mycompany.myapp+json" }, { "href": "/payment/booking", "method": "POST", "rel": "pay", "type": "application/vnd.mycompany.myapp+json" }, { "href": "/booking/1616163", "method": "DELETE", "rel": "cancel", "type": "application/vnd.mycompany.myapp+json" }, ] } } Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 42/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Pay through another resource POST /payment/booking HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth ... { "booking": "/booking/1616163", "cardno": "4111-1111-1111-1111", "expires": "04/2014", "name": "Guy Kloss", "amount": { "currency": "NZD", "value": 1414.00 } } HTTP/1.1 201 Created Location: /payment/booking/54321 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 43/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Can’t delete booking (already paid) OPTIONS /booking/1616163 HTTP/1.1 Host: www.mycompany.co.nz Authorization: OAuth ... HTTP/1.1 200 OK Allow: GET Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 44/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples We can fetch our e-Ticket now GET /booking/1616163 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Authorization: OAuth ... HTTP/1.1 200 OK Content-type: application/vnd.mycompany.myapp-v1.0+json { "flight": { "flightno": "NZ1234", "time": "4:20", "links": [ { "href": "/flight/15263", "method": "GET", "rel": "details", "type": "application/vnd.mycompany.myapp+json" } ] }, "payment": { "status": "Paid in full" "links": [ { "href": "/payment/booking/54321", "method": "GET", "rel": "details", "type": "application/vnd.mycompany.myapp+json" } ] }, "links": [ { "href": "/eticket/12415156261616", "method": "GET", "rel": "eticket", "type": "application/pdf" } ] } Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 45/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Outline 1 REST APIs Identification of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags & Optimistic Locking 5 REST Examples Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 46/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples (Common) Pitfalls of REST Design Versioning Methods in URI One URI per resource Controller resources & non-CRUD Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 47/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Versioning  /api/v1.1/article/1234/photos  /api/v1.2/article/1234/photos Different resources? Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 48/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Versioning OK: GET /api/article/1234/photos HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp+json ; version = 1.0  Better: GET /api/article/1234/photos HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json GET /api/article/1234/photos HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1.1+json GET /api/article/1234/photos HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v5.0.4a+json Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 49/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Versioning Why? It doesn’t break the resource’s URI → Same resource → Easier to evolve! See also: http://barelyenough.org/blog/2008/05/versioning-rest-web-services/ Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 50/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Methods in URI /api/get/articles/1234/photos /api/articles/new /api/articles/list Don’t use verbs in REST URIs! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 51/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples One URI per Resource /api/article/1234 /api/article/red+teddybear Different resources!?! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 52/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples One URI per Resource If you must . . . GET /api/article/red+teddybear HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json HTTP/1.1 302 Found Location: /api/article/1234 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 53/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Controller Resources & Non-CRUD Outside the CRUD? Multiple operations simultaneously? Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 54/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Controller Resources & Non-CRUD POST /distance HTTP/1.1 Host: www.mycompany.co.nz Accept: application/json Content-type: application/json;charset=UTF-8 { "from": "Auckland, NZL", "to": "Hamilton, NZL" } or: GET /distance?from=...&to=... HTTP/1.1 Host: www.mycompany.co.nz Accept: application/json HTTP/1.1 200 OK Content-length: 123 Content-type: application/json { "km": 127.5, "miles": 78.9 } Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 55/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Controller Resources & Non-CRUD POST /user/gkloss/address_merge HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Content-type: application/csv;charset=UTF-8 John Doe, 1 Main Street, Seattle, WA Jane Doe, 100 North Street, Los Angeles, CA HTTP/1.1 303 See other Location: /user/gkloss/addressbook Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 56/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Outline 1 REST APIs Identification of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags & Optimistic Locking 5 REST Examples Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 57/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples More Important Stuff HTTP Status codes ETags Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 58/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples HTTP Status Codes Status codes are important They represent the result of your actions See: http://en.wikipedia.org/wiki/Http_status_codes Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 59/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples HTTP Status Codes 1xx → Informational 2xx → Success 3xx → Redirection 4xx → Client error 5xx → Server error Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 60/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples HTTP Status Codes Important 2xx Codes 200 OK → Resource returned 201 Created → Resource created 204 No content → Resource deleted Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 61/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples HTTP Status Codes Important 3xx Codes 301 Moved Permanently → Resource reorganised 302 Found → Redirection for specific object (e. g. search) 303 Other → A redirect due to an operation 304 Not modified → Resource wasn’t changed Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 62/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples HTTP Status Codes Important 4xx Codes 400 Bad request → Incorrect payload 401 Unauthorized → Not authorized to operate 403 Forbidden → Not authorized to operate 404 Not found → Resource was not found 405 Method not allowed → Method incorrect 406 Not acceptable → Cannot return in correct format 412 Precondition failed → “ETag mismatch” (418 I’m a teapot → Hyper Text Coffee Pot Control Protocol) Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 63/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples HTTP Status Codes 501 Not implemented vs. 405 Method not allowed 409 Conflict vs. 412 Precondition failed → de·bat·a·ble/di’b¯ at b l/Adjective Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 64/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Useful HTTP Headers If-Unmodified-Since (problem: only 1 second granularity) If-Match and If-None-Match (used with ETag value) Remember: State can change in the meantime Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 65/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples ETags & Optimistic Locking GET /blogpost/12345 HTTP/1.1 Host: www.mycompany.co.nz HTTP/1.1 200 OK Content-length: 12340 Content-type: application/json ETag: abcd-1234 { "author": "Guy Kloss", "title": "Frobnification of Sub-Marine Vehicles", ... } Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 66/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples ETags & Optimistic Locking For Caching GET /blogpost/12345 HTTP/1.1 Host: www.mycompany.co.nz If-None-Match: abcd-1234 HTTP/1.1 304 Not modified → Blog post is cached and can be used Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 67/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples ETags & Optimistic Locking For Concurrency Protection PATCH /blogpost/12345 HTTP/1.1 Host: www.mycompany.co.nz If-Match: abcd-1234 { "author": "Heinrich von Zinkeduetten" } HTTP/1.1 412 Precondition failed Blog post was concurrently modified by “someone” HTTP PATCH performs a partial update Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 68/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Outline 1 REST APIs Identification of Resources Manipulation of Resources Self-Descriptive Messages HATEOAS 2 Example Scenario 3 Pitfalls of REST Design 4 More Leveraging HTTP HTTP Status Codes ETags & Optimistic Locking 5 REST Examples Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 69/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples An XML Example Just to show you, it does work with XML, too. PUT /booking/1616163 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+xml Authorization: OAuth ... /flight/15263 17F halal HTTP/1.1 200 OK Conent-type: application/vnd.mycompany.myapp-v1.0+xml Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 70/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Creating a Resource POST /articles HTTP/1.1 Host: www.mycompany.co.nz Content-type: application/vnd.mycompany.myapp-v1+json { "name": "Teddybear", "colour": "red", "stock": 15, "price": { "EUR": 15.95, "NZD": 26.95 } } HTTP/1.1 201 Created Location: /articles/1234 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 71/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Getting a Resource Collection GET /articles HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json HTTP/1.1 200 OK Content-length: 12345 Content-type: application/vnd.mycompany.myapp-v1.0+json Date: sun, 08 Aug 2013 12:34:56 NZST { "articles": [ { "name": "Rubic’s Cube", "links": [ { "href": "/articles/1233", "method": "GET", "rel": "article", "type": "application/vnd.mycompany.myapp+json" } ] }, { "name": "Teddybear", "links": [ { "href": "/articles/1234", "method": "GET", "rel": "article", "type": "application/vnd.mycompany.myapp+json" } ] } ] } Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 72/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Getting a Resource GET /articles/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json HTTP/1.1 200 OK Content-length: 12345 Content-type: application/vnd.mycompany.myapp-v1.0+json ETag: 23709-12135125 Date: sun, 08 Aug 2013 12:34:56 NZST { "name": "Teddybear", "manufacturer": "Steiff", "colour": "red", "stock": 30, ... } HTTP/1.1 404 Not found Content-length: 0 Date: sun, 08 Aug 2013 12:34:56 NZST Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 73/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Deleting a Resource DELETE /articles/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json HTTP/1.1 204 No content Content-length: 0 Date: sun, 08 Aug 2013 12:34:56 NZST Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 74/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Updating a Resource PUT /articles/1234 HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json If-Match: 23709-12135125 { "name": "Teddybear", "manufacturer": "Steiff", "colour": "red", "stock": 30, "price": { "EUR": 15.95, "NZD": 26.95 } } HTTP/1.1 200 OK Content-length: 0 Date: sun, 08 Aug 2013 12:34:56 NZST HTTP/1.1 412 Precondition failed Content-length: 0 Date: sun, 08 Aug 2013 12:34:56 NZST Idempotent! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 75/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Updating a Resource PUT is an idempotent operation It (completely) replaces the content of the whole resource Consider PATCH for partial updates! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 76/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Controller Resources (Non-CRUD) Revisited . . . POST /user/gkloss/address_merge HTTP/1.1 Host: www.mycompany.co.nz Accept: application/vnd.mycompany.myapp-v1+json Content-type: application/csv;charset=UTF-8 John Doe, 1 Main Street, Seattle, WA Jane Doe, 100 North Street, Los Angeles, CA HTTP/1.1 303 See Other Location: /user/gkloss/addressbook Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 77/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Conclusion Web-based services are about state machines and business protocols → The HATEOAS constraint from REST What can be called “RESTful” depends on who you ask (it’s not a formally accepted definition) Some say: You are not RESTful without hypermedia I say: REST is about Representational State Transfer, and hypermedia is an add-on (though very important)  There are still good APIs without hypermedia (e. g. Amazon S3)  There are very bad APIs (pretending to be RESTful) (e. g. Twitter API) If in doubt, certain APIs can be considered “RESTish” Certain ones are definitely no more than RESTish! Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 78/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Comparison REST vs. SOAP Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 79/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples Comparison REST vs. SOAP Both are request/response type services SOAP is more an RPC-style API (procedures with verb) REST is about REST (duh!) SOAP has strictly defined interfaces, and the communication can be verified REST is more about evolving APIs, and making them explorable through hypermedia Bells’n’whistles in SOAP, but can be found in REST (less obvious, less used: WADL, JSON schema, . . . ) Use . . . SOAP for well managed “corporate-style” consumers REST for many, less-defined “citizen consumers” REST if the API is likely to evolve Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 80/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples More Reading Wikipedia: Representational State Transfer http://en.wikipedia.org/wiki/Representational_State_Transfer Roy Fielding’s PhD dissertation coming up with the REST idea: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm “RESTful Web Services Cookbook – Solutions for Improving Scalability and Simplicity” http://oreilly.com/catalog/9780596801694 Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 81/84 

REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples More Reading Online Slide Presentations “Designing HTTP Interfaces and RESTful Web Services” http://www.slideshare.net/Wombert/ designing-http-interfaces-and-restful-web-services-dpc2012-20120608 “HATEOAS: The Confusing Bit from REST” http://www.slideshare.net/adorepump/ hateoas-the-confusing-bit-from-rest “REST in Practice” http://www.slideshare.net/guilhermecaelum/rest-in-practice “RESTful Web APIs with Python, Flask and MongoDB” https://speakerdeck.com/nicola/ developing-restful-web-apis-with-python-flask-and-mongodb Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS 82/84 

KIWI PYCON AUCKLAND 2013 THE YEAR OF THE SNAKE New Zealand's premier Python event of the year http://nz.pycon.org/ Kiwi PyCon 2013 will be held at Auckland University of Technology's new "Sir Paul Reeves Building", also known as building "WG" at AUT's city campus. SEPTEMBER 6-8 THANKS TO SIMPLICITY AKL FLEXIBILITY BEAUTY 

Questions? Image used under Creative Commons from Boston Public Library http://flickr.com/boston_public_library/