This document discusses HATEOAS (Hypermedia as the Engine of Application State) and how it relates to RESTful web services. It introduces the Richardson maturity model for RESTful services and emphasizes that hypermedia formats are important for enabling HATEOAS. Some key hypermedia formats discussed are XHTML, Atom, and a custom XML format. The document also provides an example workflow for ordering coffee from a hypothetical RESTful service called Restbucks to illustrate how the state of an application can be driven by following hypermedia links between resources.
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
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
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
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