1. HATEOAS:
The Confusing Bit from REST Dr. Jim Webber
http://jim.webber.name

2. whoami
• PhD in parallel computing
– Speciality in programming language design(!)
• {developer, architect, director} with
ThoughtWorks
• Author of “Developing Enterprise Web
Services”
– And currently engaged in writing a book on
Web-as-middleware

3. Roadmap
• The Richardson Maturity Model
• Hypermedia Formats
• HATEOAS – Hypermedia As The Engine Of
Application State
• Semantics
• A Simple RESTful Service
• Cheap sales-pitch for our book

4. The Richardson Maturity Model
• Level 0
– SOAP, XML RPC, POX
– Single URI
Hypermedia
• Level 1
– URI Tunnelling
– Many URIs, Single verb
• Level 2 HTTP
– Many URIs, many verbs
– CRUD services (e.g.
Amazon S3)
• Level 3 URI
– Level 2 + Hypermedia
– RESTful Services

5. Why the Web? Why be RESTful?
• Scalable
• Fault-tolerant
• Recoverable
• Secure
• Loosely coupled
• Precisely the same characteristics we
want in business software systems!

6. Media Types Rule!
• The Web’s contracts are expressed in
terms of media types
– If you know the type, you can process the
content
• Some types are special because they work
in harmony with the Web
– We call these “hypermedia formats”

7. Other Resource Representations
• Remember, XML is not the only way a resource can be
serialised
– Remember the Web is based on REpresentational State
Transfer
• The choice of representation is left to the implementer
– Can be a standard registered media type
– Or something else
• But there is a division on the Web between two families
– Hypermedia formats
• Formats which host URIs and links
– Regular formats
• Which don’t

8. Plain Old XML is not Hypermedia
Friendly
HTTP/1.1 200 OK
Where are the links?
Content-Length: 227
Where’s the protocol?
Content-Type: application/xml
Date: Wed, 19 Nov 2008 21:48:10 GMT
<order xmlns="http://schemas.restbucks.com/order">
<location>takeAway</location>
<items>
<item>
<name>latte</name>
<quantity>1</quantity>
<milk>whole</milk>
<size>small</size>
</item>
</items>
<status>pending</pending>
</order>

9. So what?
• How do you know the next thing to do?
• How do you know the resources you’re
meant to interact with next?
• In short, how do you know the service’s
protocol?
– Turn to WADL? Yuck!
– Read the documentation? Come on!
– URI Templates? Tight Coupling!

10. URI Templates are NOT a
Hypermedia Substitute
• Often URI templates are used to advertise all resources a
service hosts
– Do we really need to advertise them all?
• This is verbose
• This is out-of-band communication
• This encourages tight-coupling to resources through their URI
template
• This has the opportunity to cause trouble!
– Knowledge of “deep” URIs is baked into consuming programs
– Services encapsulation is weak and consumers will program to
it
– Service will change its implementation and break consumers

11. application/xml is not the media
type you’re looking for
• Remember that HTTP is an application protocol
– Headers and representations are intertwined
– Headers set processing context for representations
– Unlike SOAP which can safely ignore HTTP headers
• It has its own header model
• Remember that application/xml has a particular
processing model
– Which doesn’t include understanding the semantics of links
• Remember if a representation is declared in the Content-
Type header, you must treat it that way
– HTTP is an application protocol – did you forget already? 
• We need real hypermedia formats!

12. Hypermedia Formats
• Standard
– Wide “reach”
– Software agents already know how to process
them
– But sometimes need to be shoe-horned
• Self-created
– Can craft specifically for domain
– Semantically rich
– But lack reach

13. Two Common Hypermedia Formats:
XHTML and ATOM
• Both are commonplace today
• Both are hypermedia formats
– They contain links
• Both have a processing model that
explicitly supports links
• Which means both can describe
protocols…

14. application/vnd.restbucks+xml
• What a mouthful!
• The vnd namespace is for proprietary media
types
– As opposed to the IANA-registered ones
• Restbucks own XML is a hybrid
– We use plain old XML to convey information
– And link elements to convey protocol
• This is important, since it allows us to
create RESTful, hypermedia aware services

15. Interlude: Microformats
• Microformats are an example of little “s”
semantics
• Innovation at the edges of the Web
– Not by some central design authority (e.g. W3C)
• Started by embedding machine-processable
elements in Web pages
– E.g. Calendar information, contact information,
etc
– Using existing HTML features like class, rel,
etc

16. Semantic versus semantic
• Semantic Web is top-down
– Driven by the W3C with extensive array of technology,
standards, committees, etc
– Has not currently proven as scalable as the visionaries hoped
• RDF tripples have been harvested and processed in private databases
• Microformats are bottom-up
– Little formal organisation, no guarantee of interoperability
– Popular formats tend to be adopted (e.g. hCard)
– Easy to use and extend for our systems
– Trivial to integrate into current and future programmatic Web
systems

17. Microformats and Resources
• Use Microformats to structure resources where
formats exist
– I.e. Use hCard for contacts, hCalendar for data
• Create your own formats (sparingly) in other
places
– Annotating links is a good start
– <link rel="withdraw.cash" .../>
– <link rel="service.post"
type="application/atom+xml"
href="{post-uri}" title="some title">
• The rel attribute describes the semantics of the
referred resource

18. Revisiting Resource Lifetime
• On the Web, the lifecycle of a single resource is
more than:
– Creation
– Updating
– Reading
– Deleting
• Can also get metadata
– About the resource
– About its (subset of) the verbs it understands
• And as we see, resources tell us about other
resources we might want to interact with…

19. Links
• Connectedness is good in Web-based
systems
• Resource representations can contain
other URIs
• Links act as state transitions
• Application (conversation) state is
captured in terms of these states

20. Describing Contracts with Links
• The value of the Web is its “linked-ness”
– Links on a Web page constitute a contractfor page
traversals
• The same is true of the programmatic Web
• Use Links to describe state transitions in
programmatic Web services
– By navigating resources you change application state
• Hypermedia formats support this
– Allow us to describe higher-order protocols which sit
comfortably atop HTTP
– Hence application/vnd.restbucks+xml

21. Links are State Transitions

22. Links as APIs
<confirm xmlns="..."> • Following a link
<link rel="payment"
href="https://pay"
causes an action to
type="application/xml"/>
occur
<link rel="postpone" • This is the start of a
href="https://wishlist" state machine!
type="application/xml"/>
</confirm>
• Links lead to other
resources which also
have links
• Can make this
stronger with
semantics
– Microformats

23. We have a framework!
• The Web gives us a processing and metadata
model
– Verbs and status codes
– Headers
• Gives us metadata contracts or Web “APIs”
– URI Templates
– Links
• Strengthened with semantics
– Little “s”

24. Workflow
• How does a typical enterprise workflow look
when it’s implemented in a Web-friendly
way?
• Let’s take Starbuck’s as an example, the
happy path is:
– Make selection
• Add any specialities
– Pay
– Wait for a while
– Collect drink

25. Workflow and MOM
• With Web Services we
exchange messages
with the service
• Resource state is
hidden from view
• Conversation state is
all we know
– Advertise it with
SSDL, BPEL
• Uniform interface,
roles defined by SOAP
– No “operations”

26. Hypermedia Describes Protocols!
• Links declare next valid steps
• Following links and interacting with
resources changes application state
• Media types with links define contracts
– Media type defines processing model
– Links (with microformats) describe state
transistions
• Don’t need a static contract description
– No WSDL, no WADL
• This is HATEOAS!

27. Web-friendly Workflow
• What happens if workflow stages are modelled as resources?
• And state transitions are modelled as hyperlinks or URI
templates?
• And events modelled by traversing links and changing
resource states?
• Answer: we get Web-friendly workflow
– With all the quality of service provided by the Web
• So let’s see how we order a coffee at Restbucks.com…
– This is written up on the Web:
• http://www.infoq.com/articles/webber-rest-workflow

28. Placing an Order
• Place your order by POSTing it to a well-
known URI
– http://example.restbucks.com/order
Starbuck’s Service
Client

29. Placing an Order: On the Wire
• Response
• Request 201 Created
Location: http://restbucks.com/
POST /order HTTP 1.1
order/1234
Host: restbucks.com Content-Type: application/
Content-Length: ... vnd.restbucks+xml
Content-Length: ...
<order xmlns="urn:restbucks">
<drink>latte</drink> <order xmlns="urn:restbucks">
</order> <drink>latte</drink>
<link rel="payment"
If we have a (private) href="https://restbucks.com/
A link! Is this the
microformat, this can payment/order/1234"
start of an API?
become a neat API! type="application/xml"/>
</order>

30. Whoops! A mistake
• I like my coffee to taste like coffee!
• I need another shot of espresso
– What are my OPTIONS?
 Request  Response
OPTIONS /order/1234 HTTP 1.1 200 OK
Host: restbucks.com Allow: GET, PUT Phew! I can
update my
order, for now

31. Optional: Look Before You Leap
• See if the resource has changed since you
submitted your order
– If you’re fast your drink hasn’t been
prepared yet
 Request  Response
PUT /order/1234 HTTP 1.1 100 Continue
Host: restbucks.com I can still PUT this
Expect: 100-Continue
resource, for now.
(417 Expectation
Failed otherwise)

32. Amending an Order
• Add specialities to you order via PUT
– Restbucks needs 2 shots!
Starbuck’s Service
Client

33. Amending an Order: On the Wire
• Request • Response
PUT /order/1234 HTTP 1.1 200 OK
Host: restbucks.com Location: http://restbucks.com/
Content-Type: application/ order/1234
vnd.restbucks+xml Content-Type: application/
Content-Length: ... vnd.restbucks+xml
Content-Length: ...
<order xmlns="urn:restbucks">
<drink>latte</drink> <order xmlns="urn:restbucks">
<additions>shot</additions> <drink>latte</drink>
<link rel="payment" <additions>shot</additions>
href="https://restbucks.com/ <link rel="payment"
payment/order/1234" href="https://restbucks.com/
type="application/xml"/> payment/order/1234"
</order> type="application/xml"/>
</order>

34. Statelessness
• Remember interactions with resources are stateless
• The resource “forgets” about you while you’re not
directly interacting with it
• Which means race conditions are possible
• Use If-Unmodified-Since on a timestamp to
make sure
– Or use If-Match and an ETag
• You’ll get a 412 PreconditionFailed if you lost
the race
– But you’ll avoid potentially putting the resource into
some inconsistent state

35. Warning: Don’t be Slow!
• Can only make changes until someone
actually makes your drink
– You’re safe if you use If-Unmodified-Since
or If-Match
– But resource state can change without you!
 Request
 Response
PUT /order/1234 HTTP 1.1
Host: restbucks.com
409 Conflict
... Too slow! Someone else has
changed the state of my order
 Request  Response
OPTIONS /order/1234 HTTP 1.1 Allow: GET
Host: restbucks.com

36. Order Confirmation
• Check your order status by GETting it
Starbuck’s Service
Client

37. Order Confirmation: On the Wire
• Request • Response
GET /order/1234 HTTP 1.1 200 OK
Host: restbucks.com Location: http://restbucks.com/
order/1234
Content-Type: application/
vnd.restbucks+xml
Content-Length: ...
<order xmlns="urn:restbucks">
<drink>latte</drink>
<additions>shot</additions>
Are they trying to tell me <link rel="payment" href="https://
something with hypermedia? restbucks.com/payment/order/1234"
type="application/xml"/>
</order>

38. Order Payment
• PUT your payment to the order resource
https://restbucks.com/payment/order/1234
Starbuck’s Service
Client
New resource!
https://restbucks.com/payment/order/1234

39. How did I know to PUT?
• The client knew the URI to PUT to from the link
– PUT is also idempotent (can safely re-try) in case of failure
• Verified with OPTIONS
– Just in case you were in any doubt 
 Request  Response
OPTIONS /payment/order/1234 HTTP 1.1 Allow: GET, PUT
Host: restbucks.com

40. Order Payment: On the Wire
• Request • Response
PUT /payment/order/1234 HTTP 1.1 201 Created
Host: restbucks.com Location: https://
Content-Type: application/xml restbucks.com/payment/order/
Content-Length: ... 1234
Content-Type: application/xml
Content-Length: ...
<payment xmlns="urn:restbucks">
<cardNo>123456789</cardNo>
<expires>07/07</expires>
<name>John Citizen</name> <payment xmlns="urn:restbucks">
<amount>4.00</amount> <cardNo>123456789</cardNo>
</payment> <expires>07/07</expires>
<name>John Citizen</name>
<amount>4.00</amount>
</payment>

41. Check that you’ve paid
• Request • Response
GET /order/1234 HTTP 1.1 200 OK
Host: restbucks.com Content-Type: application/
vnd.restbucks+xml
Content-Length: ...
My “API” has changed,
because I’ve paid <order xmlns="urn:restbucks">
enough now <drink>latte</drink>
<additions>shot</additions>
</order>

42. Finally drink your coffee...
Source: http://images.businessweek.com/ss/06/07/top_brands/image/restbucks.jpg

43. Summary
• Web-based services are about state
machines, and business protocols
– The HATEOAS constraint from REST
• If you don’t use hypermedia, you are NOT
RESTful
– Which is OK! Good systems don’t always have to
be RESTful – e.g. Amazon S3
• Use Web for massive scalability, fault
tolerance
– If you can tolerate higher latencies

44. Restbucks Written Up @ InfoQ
http://www.infoq.com/articles/webber-rest-workflow

45. Questions?
Blog:
http://jim.webber.name
GET /Connected
Jim Webber
Savas Parastatidis
Ian Robinson
Coming 2009…