2. Hypermedia is defined by the
presence of application
control information
embedded within, or as a
layer above, the presentation
of information.
Mike Amudsen
3
“
4. “
HYPERMEDIA IS THE ENGINE
Hypermedia payloads carry more
information than just the data stored
on the server. Hypermedia payloads
carry two types of vital metadata:
metadata about the data itself and
metadata about the possible options
for modifying the state of the
application at that moment.
Mike Amudsen
5
5. THE HYPERMEDIA
CONSTRAINT
The application is therefore an
engine that moves from one state
to the next by examining and
choosing from among the
alternative state transitions in the
current set of representations.
Roy Fielding
6
“
8. LINKED DATA PRINCIPLES
1.Use URIs as names for things
2.Use HTTP URIs so that people can look up those
names.
3.When someone looks up a URI, provide useful
information, using the standards
4.Include links to other URIs so that they can
discover more things.
Tim Berners-Lee (2006)
http://www.w3.org/DesignIssues/LinkedData.html
9
9. EXAMPLE: CHECK BANK ACCOUNT
BALANCE
EXPLORABLE API + INLINE
DOCUMENTATION
GET /account/12345
200 OK
<?xml version="1.0"?>
<account>
<account_number>12345</account_number>
<link rel=“self” href=“/account/12345” />
<balance currency="usd">100.00</balance>
<link rel=“http://bank.org/rel/first-subscriber" href="/customer/123" />
<link rel=“http://bank.org/rel/subscribers" href="/account/12345/subscriber" />
<link rel="http://bank.org/rel/deposit" href="/account/12345/deposit" />
<link rel="http://bank.org/rel/withdraw" href="/account/12345/withdraw" />
<link rel="http://bank.org/rel/transfer" href="/account/12345/transfer" />
<link rel="http://bank.org/rel/close" href="/account/12345/close" />
</account>
10
Semantic
and
documentati
on
Use URI as
names
Explorable
10. CLIENT SIMPLICITY
Coupled to
implementation
res = GET /account/123
If enough-funds() then
msg = build-withdraw-
message()
url = build-url-from-
template()
POST msg @ url
Endif
Hypermedia-driven
res = GET /account/123
If res.hasLink(“withdraw”) then
msg = build-withdraw-
message()
POST msg @
res.link(“withdraw”)
Endif
11
Needs to
know URL
template
Business
logic spills
out to client
Server
handles
Business
logic
Server
manages URL
structure
VS
12. EXAMPLE: CHECK BANK ACCOUNT
BALANCE
SERVER MODIFIES URL
STRUCTURE
GET /account/12345
200 OK
<?xml version="1.0"?>
<account>
<account_number>12345</account_number>
<link rel=“self” href=“/account/12345” />
<balance currency="usd">100.00</balance>
<link rel=“http://bank.org/rel/first-subscriber"
href=“/crm/123?role=customer" />
<link rel=“http://bank.org/rel/subscribers" href="/account/12345/subscriber" />
<link rel="http://bank.org/rel/deposit" href="/account/12345/deposit" />
<link rel="http://bank.org/rel/withdraw" href="/account/12345/withdraw" />
<link rel="http://bank.org/rel/transfer" href="/account/12345/transfer" />
<link rel="http://bank.org/rel/close" href="/account/12345/close" />
</account>
13
New URL; no
problem client just
follows it
13. EXAMPLE: CHECK BANK ACCOUNT
BALANCE
CONTENT OFFLOADING
GET /account/12345
200 OK
<?xml version="1.0"?>
<account>
<account_number>12345</account_number>
<link rel=“self” href=“/account/12345” />
<balance currency="usd">100.00</balance>
<link rel=“http://bank.org/rel/first-subscriber"
href=“http://one-crm.com/api/tenant/bankABC/prospect/754" />
<link rel=“http://bank.org/rel/pricing"
href=“http://bankABC.cdn.akamai.com/static/pricing" />
...
</account>
14
Content offloaded
to 3rd party
providers
14. EXAMPLE: CHECK BANK ACCOUNT
BALANCE
SERVER UPGRADE
GET /account/12345
200 OK
<?xml version="1.0"?>
<account>
<account_number>12345</account_number>
<link rel=“self” href=“/account/12345” />
<balance currency="usd">100.00</balance>
<link rel=“http://bank.org/rel/first-subscriber"
href=“http://one-crm.com/api/tenant/bankABC/prospect/754" />
<link rel=“http://bank.org/rel/pricing"
href=“http://bankABC.cdn.akamai.com/static/pricing" />
<link rel="http://bank.org/rel/deposit"
href="/account/12345/deposit"
type=“application/vnd.bankABC.deposit.v2+xml,
application/vnd.bankABC.deposit+xml” />
...
</account> 15
New relationship;
only V2 clients will
know it
New media type
accepted; only V2
clients will know it
18. Jørn Wildt (2013) Selling the benefits of hypermedia APIs.
http://soabits.blogspot.no/2013/12/selling-benefits-
of-hypermedia.html
David (2012) Getting hyper about hypermedia APIs.
https://signalvnoise.com/posts/3373-getting-hyper-
about-hypermedia-apis
“Architectural Styles and the Design of Network-based
Software Architectures”, PhD Thesis (2000), Roy Thomas
Fielding.
http://www.ics.uci.edu/~fielding/pubs/dissertation/top.
htm
Leonard Richardson, Mike Amundsen, RESTful web APIs.
O’Reily Media. ISBN: 1449358063
From wikipedia: http://en.wikipedia.org/wiki/HATEOAS
This principle is the key differentiator between a REST and most other forms of client server system.
Rather than the actions and interfaces a client may use being defined elsewhere, such as in a WSDL file or predefined in the client code, the principle is that the hypermedia in eachserver response will contain links that correspond to all the actions that the client can currently perform. Therefore, dependent on the current application state, every server response describes the new actions that are available. The server can change the range of allowable responses in a dynamic way, and a client should adapt its behavior to these changes.
A client of a RESTful application need only know a single fixed URL to access it. All future actions should be discoverable dynamically from hypermedia links included in the representations of the resources that are returned from that URL. Standardized media types are also expected to be understood by any client that might use a RESTful API. Application state transitions are driven by a combination of the known processing rules for each media type, client selection from the server-provided choices in representations received, and the user's manipulation of those representations. Thus interactions are driven by hypermedia, rather than by any out-of-band information.[1]
If necessary, the client’s knowledge of media types, resource communication mechanisms, and user interaction, may be improved on-the-fly by the transmission of code-on-demand from the server to the client as defined elsewhere in the REST architecture.[2]
Old clients will ignore the relationships they don’t understand and will continue to send V1 representations while new clients will understand the new relationships and will take advantage of V2 representations