Discover the benefits of making your APIs hypermedia-driven

1. BENEFITS OF
HYPERMEDIA APIS
Paulo Gandra de
Sousa
pagsousa@gmail.co
m

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
“

3. THE HYPERMEDIA
CONSTRAINT
Hipermedia as the
engine of application
state *
* HATEOAS

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
“

6. IMMEDIATE BENEFITS
Explorable API
Inline documentation
Simple client logic
7

7. “BILLBOARD” ENDPOINT
GET /api
8
200 Ok
<links>
<link rel=“…” href=“…”/>
<link rel=“…” href=“…”/>
...
</links>

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

11. FLEXIBILITY & EVOLUTION
Server takes ownership of URL
Offloading content
Upgrading
12

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

15. 16
CLOSINGS

16. 1. Adhere to the
hypermedia constraint
2. Aim for a “billboard”
API
3. Decouple client and
server

17. REFERENCES

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