This document outlines Representational State Transfer (REST) and HATEOAS (Hypermedia as the Engine of Application State). It discusses the principles of REST including identification of resources, manipulation of resources through HTTP methods, self-descriptive messages, and HATEOAS. An example scenario of a flight booking API is provided to illustrate how HATEOAS links indicate state transitions within a REST API.

1. 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/

2. 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

3. 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

4. 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

5. 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

6. 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

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

8. 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

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

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

11. 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

12. 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?order=sizelimit=5
/photos/limit/5/order/size
/photos?limit=5order=size
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS
12/84

13. 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

15. 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
Delete = DELETE
PATCH)
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS
15/84

16. REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Manipulation of Resources
Creating a Resource
creates a new resource
But the server decides on that resources URI
Examples
POST
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

17. 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

18. 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

19. 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

20. 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

21. 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

22. 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

23. 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

24. 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

25. 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

26. 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

27. 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

28. 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

29. 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

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

31. 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

32. 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

33. 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

34. 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

35. REST APIs Example Scenario Pitfalls of REST Design More Leveraging HTTP REST Examples
Search for Specified Flights
POST /search?order=pricelimit=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

36. 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

37. 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

38. 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

39. 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

40. 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

41. 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

42. 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

43. 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

44. 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

45. 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

46. 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

47. 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

48. 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

49. 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

50. 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

51. 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

52. 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

53. 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

54. 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

55. 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

56. 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

57. 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

58. 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

59. 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

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

61. 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

62. 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

63. 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

64. 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¯t b l/Adjective
a
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS
64/84

65. 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

66. 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

67. 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

68. 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

69. 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

70. 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 ...
booking
flight/flight/15263/flight
seat17F/seat
mealhalal/meal
/booking
HTTP/1.1 200 OK
Conent-type: application/vnd.mycompany.myapp-v1.0+xml
booking
link rel=details href=/booking/1616163
method=GET type=application/vnd.mycompany.myapp+xml
link rel=payment href=/payment/booking
method=POST type=application/vnd.mycompany.myapp+xml
link rel=cancel href=/booking/1616163
method=DELETE type=application/vnd.mycompany.myapp+xml
/booking
Service-Oriented Architecture | Representational State Transfer (REST) and HATEOAS
70/84

71. 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

72. 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

73. 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

74. 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

75. 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

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

77. 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

78. 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

79. 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

80. 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

81. 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

82. 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

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

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