Embed Size (px)
Citation preview
3” Hypermedia is defined by the presence of application control information embedded within, or as a layer above, the presentation of information.
Mike Amudsen
“
THE HYPERMEDIA CONSTRAINT
Hipermedia as the engine of
application state *
* HATEOAS
5
“”
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
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
“”
7
IMMEDIATE BENEFITS Explorable API Inline documentation Simple client logic
8
“BILLBOARD” ENDPOINT
GET /api200 Ok<links><link rel=“…” href=“…”/><link rel=“…” href=“…”/>...</links>
9
LINKED DATA PRINCIPLES
1.Use URIs as names for things2.Use HTTP URIs so that people can look up those
names.3.When someone looks up a URI, provide useful
information, using the standards4.Include links to other URIs so that they can discover
more things.
Tim Berners-Lee (2006) http://www.w3.org/DesignIssues/LinkedData.html
10
EXAMPLE: CHECK BANK ACCOUNT BALANCEEXPLORABLE 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> Semantic
and documentat
ion
Use URI as names
Explorable
11
CLIENT SIMPLICITYCoupled 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”)
EndifNeeds to know URL template
Business logic spills
out to client
Server handles Business
logic
Server manages
URL structure
VS
12
FLEXIBILITY & EVOLUTION Server takes ownership of URL Offloading content Upgrading
13
EXAMPLE: CHECK BANK ACCOUNT BALANCESERVER 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>
New URL; no problem client just follows it
14
EXAMPLE: CHECK BANK ACCOUNT BALANCECONTENT 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>
Content offloaded to 3rd party providers
15
EXAMPLE: CHECK BANK ACCOUNT BALANCESERVER 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>
New relationship; only V2 clients
will know it
New media type accepted; only V2 clients will know it
16
CLOSINGS
1. Adhere to the hypermedia constraint
2. Aim for a “billboard” API
3. Decouple client and server
REFERENCES
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
