A short intro on how to design an hypermedia API

1. HYPERMEDIA
APIS
Paulo Gandra de
Sousa
pag@isep.ipp.pt

2. 2
ISEP/IPP
Building Hypermedia APIs with HTML5 and
Node
 Mike Amundsen
 ISBN: 978-1-4493-0657-1
RESTful web APIs
 Leonard Richardson, Mike Amundsen
 ISBN: 1449358063

3. HYPERMEDIA API
3

4. “Programming for distributed
hypermedia environments
usually means that message
transfers must carry more than
just data; they must carry
additional information including
metadata and higher-level
application flow control
options.”
Mike Amudsen 4
ISEP/IPP

5. RICHARDSON MATURITY
MODEL
http://martinfowler.com/articles/richardsonMaturityMod

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

7. 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
7
ISEP/IPP

8. HYPERMEDIA API
Focus on
the media type and its hypermedia
capabilities
not on
the API calls
9
ISEP/IPP

9. H-FACTORS
Links
 represent opportunities for a
client to advance the state of
the application by activating a
link.
Controls
 provide support for additional
metadata when executing link
operations.
Not all media types
support all h-factors
11
ISEP/IPP

10. LINK H-FACTORS
H-Factor Example
LE Embed Links <img src=“…”>
LO Outbound
Links
<a href=“…”>
LT Templated
Links
<form method="get" action=“…">
<input type="text" name="search" value="" />
<input type="submit" />
</form>
LI Idempotent
Links
<link rel="edit" href=“…"/> (ATOM)
LN Non-
Idempotent
Links
<form method="post" action=“…">
<textarea name="comment"></textarea>
<input type="submit" />
</form>
12
ISEP/IPP

11. CONTROL H-FACTORS
H-Factor Example
CR Read Controls Accept-Language: (http header)
CU Update
Controls
<form method="post“ action=“…"
enctype="text/plain">
<textarea name="comment"></textarea>
<input type="submit" />
</form>
CM Method
Controls
<form method="post“ action=“…">
<textarea name="comment"></textarea>
<input type="submit" />
</form>
CL Link
Annotation
Controls
<link rel="stylesheet" href="..." />
13
ISEP/IPP

12. HYPERMEDIA MEDIA
TYPE DESIGN
14

13. MEDIA TYPE
Describes the message structure and semantic
Use standard media types as much as possible
 http://www.iana.org/assignments/media-types/media-types.xhtml
Not all media types are hypermedia enabled, e.g.,
image/jpeg
15
ISEP/IPP

14. EXAMPLE DATA (CSV)
darrel,admin,active
mike,manager,suspended
...
whartung,user,pending
16
ISEP/IPP

15. EXAMPLE DATA WITH
METADATA
<ul class="users">
<li class="user">
<a href="..." rel="user">darrel</a>
<span class="role">admin</span>
<span class="status">active</span>
</li>
<li class="user">
<a href="..." rel="user">mike</a>
<span class="role">manager</span>
<span class="suspended">suspended</span>
</li>
...
</ul>
17
ISEP/IPP

16. EXAMPLE APPLICATION
METADATA
<ul class="users">
<li class="navigation"> <a href="..." rel="next-page">next-page</a>
</li>
<li class="navigation"> <a href="..." rel="last-page">last-page</a>
</li>
<li class="user"> ... </li>
...
</ul>
<!-- defined filters -->
<ul class="queries">
<li class="query"><a href="..." rel="admins">admins</a></li>
<li class="query"><a href="..." rel="pending">pending</a></li>
<li class="query"><a href="..." rel="suspended">suspended</a></li>
</ul>
<!-- user search -->
<form name="user-search" action="...">
<input name="search-name" value="" />
<input type="submit" />
</form>
18
ISEP/IPP

17. HYPERMEDIA TYPE DESIGN
ELEMENTS
Base Format
(client-initiated) State Transfer
Domain Style
Application Flow
19
ISEP/IPP

18. BASE FORMAT
Plain text
CSV
JSON, XML,
HTML, Atom/AtomPub
…
20
ISEP/IPP

19. (CLIENT INITIATED) STATE
TRANSFER
None / read-only
 State is only transmitted from the server to the client
Predefined
 State transmitted from the client to the server follows predefined
payloads defined by the server and known by the client
Ad-hoc
 The server tells the client what state to trasmit. E.g., HTML <FORM>
21
ISEP/IPP

20. DOMAIN STYLE
Specific
 The payload has domain specific terms that are understood by client
and server, e.g., <shipping address>
General
 The payload uses some general blocks that can be reused in diferent
use cases, e.g., <adress type=“shipping”>
Agnostic
 The payload uses domain agnostic terms and (well known) decorators
to add semantic, e.g., <link rel=“edit”>
22

21. SPECIFIC DOMAIN STYLE
EXAMPLE
<!-- domain-specific design -->
<order>
<id>...</id>
<shipping-address>...</shipping-address>
<billing-address>...</billing-address>
...
</order>
23
ISEP/IPP

22. GENERAL DOMAIN STYLE
EXAMPLE
/* domain-general design */
{
"order":
{
"id" : "...",
"address" :
{"type" : "shipping", "street-address" : "..."},
"address" :
{"type" : "billing", "street-address" : "..."}
}
}
24
ISEP/IPP

23. AGNOSTIC DOMAIN STYLE
EXAMPLE
<!-- domain-agnostic design -->
<ul class="order">
<li class="id">...</li>
<ul class="shipping-address">
<li class="street-address">...</li>
...
</ul>
<ul class="billing-address">
<li class="street-address">...</li>
...
</ul>
...
</ul>
25
ISEP/IPP

24. APPLICATION FLOW
None
 The hypermedia type contains no identifiers for application flow.
Intrinsic
 The application flow identifiers are defined within the hypermedia
type itself. E.g., Atom and AtomPub define a small set of link
relations to indicate application flow (“edit”, “edit-media”, and “self”).
Applied
 The application flow identifiers are not part of the hypermedia type,
but the type designs contain allowances (usually element decorators
or attributes) for applying external values to indicate application flow.
E.g., HTML attributes: profile, id, name, rel, and class.
26

25. NO APPLICATION FLOW
EXAMPLE
Media type: text/uri-list
# urn:isbn:0-201-08372-8
http://www.huh.org/books/foo.html
http://www.huh.org/books/foo.pdf
ftp://ftp.foo.org/books/foo.txt
27
ISEP/IPP

26. INTRINSIC APPLICATION
FLOW EXAMPLE
<!-- AtomPub -->
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
<title>Atom-Powered Robots Run Amok</title>
<id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
<updated>2003-12-13T18:30:02Z</updated>
<author><name>John Doe</name></author>
<content>Some text.</content>
<link rel="edit" href="http://example.org/edit/first-
post.atom"/>
</entry>
28
ISEP/IPP

27. APPLIED APPLICATION FLOW
EXAMPLE
<html>
<head>
<title>Payment Options</title>
<meta name="profile" content="http://www.example.com/profiles/payment.html" />
</head>
<body>
<h1>Payment Options</h1>
<p> <a href="..." rel="cancel-order">Cancel Order</a> </p>
<form href="..." name="credit-card" method="post">
<input name="card-number" value="" />
...
<input type="submit" />
</form>
<form href="..." name="purchase-order" method="post">
<input name="po-number" value="" />
...
<input type="submit" />
</form>
<form href="..." name="bank-draft" method="post">
<input name="routing-number" value="" />
...
<input type="submit" />
</form>
...
</html>
29
ISEP/IPP

28. AN EXAMPLE Message server
30

29. SIMPLE MESSAGE SERVICE
A service that allows users to post messages.
Post a new message
Update a message
Search messages by text, user, and date
Get all the messages of one user
Register a new user
Update the user data
Upload the user photo
31
ISEP/IPP
Message
User
1
0..n

30. MESSAGES RESOURCES
Resource The message collection
URL /message
GET
POST
PUT
DELET
E
return all messages
create new entry, returns 201
not allowed
not allowed
Resource A message (Item in the collection)
URL /message/:id
GET
POST
PUT
DELET
return specific message or 404
update existing entry or 404
overwrite existing or create new given the id
deletes the message 32
ISEP/IPP

31. USERS RESOURCES
Resource The user collection
URL /user
GET
POST
PUT
DELET
E
return all users
create new entry, returns 201
not allowed
not allowed
Resource An user
URL /user/:id
GET
POST
PUT
DELET
return specific user or 404
updates existing entry or 404
overwrite existing or create new given the id
deletes the user 33
ISEP/IPP

32. NO HYPERMEDIA
REPRESENTATIONS
Message
{
id: "a1",
text: "Sample one",
sender: "Mary",
createdOn: now,
updatedOn: now
};
User
{
id: "Mary",
name:"Mary",
email: "mary@contoso.com",
roles:[],
createdOn: now
};
34
ISEP/IPP
Missing:
• Explicit id as URI
• Explicit links to other
resources
• Application flow

33. HYPERMEDIA MISSING FOR
MESSAGES
Message collection
Paging links
 First page
 Next page
 Previous page
Message Item
Resource links
 User
 Message collection
Actions
 Edit the message
 Delete the message
35
ISEP/IPP

34. HYPERMEDIA MISSING FOR
USERS
User collection
Paging links
 First page
 Next page
 Previous page
User Item
Resource links
 User’s messages
 User’s photo
 User collection
Actions
 Edit the user
 Cancel user account
36
ISEP/IPP

35. SOME DESIGN DECISIONS
Base format
 JSON
State transfer
 Predefined
Domain style
 Specific
Application flow
 Intrinsic
37
ISEP/IPP

36. LINK RELATIONS
Don’t reinvent the weel
IANA
 http://www.iana.org/assignments/link-relations/link-relations.xhtml
Microformats
 http://microformats.org/wiki/existing-rel-values
38
ISEP/IPP

37. COMMON LINK RELATIONS
rel Description Definitio
n
collecti
on
The target IRI points to a resource which
represents the collection resource for the
context IRI.
[RFC657
3]
edit Refers to a resource that can be used to
edit the link's context.
[RFC502
3]
edit-
form
The target IRI points to a resource where a
submission form for editing associated
resource can be obtained.
[RFC686
1]
next Indicates that the link's context is a part of
a series, and that the next in the series is
the link target.
[HTML5]
payme Indicates a resource where payment is [RFC598 39
ISEP/IPP
Source: http://www.iana.org/assignments/link-relations/link-relations.xht

38. Message collection
{
MESSAGE_KEY : {
MESSAGE_REPRESENTATION
},
…
links: [
{ rel: "self",
href: URI
},
{ rel: "start",
href: URI
},
{ rel: "prev",
href: URI
},
{ rel: "next",
href: URI
}
]
}
Message Item
{
text: "Sample one",
createdOn: now,
updatedOn: now,
links: [
{ rel: "self",
href:
SERVER_ROOT+"/message/a1",
},
{ rel: "edit",
href:
SERVER_ROOT+"/message/a1",
},
{ rel: "collection",
href: SERVER_ROOT+"/message"
},
{ rel: "psidi:user",
href: SERVER_ROOT+"/user/Mary",
title: "Mary Smith"
}
],
};

39. User collection
{
USER_KEY : {
USER_REPRESENTATION },
…
links: [
{ rel: "self",
href: URI
},
{ rel: "start",
href: URI
},
{ rel: "prev",
href: URI
},
{ rel: "next",
href: URI
}
]
}
UserItem
{
name:"Mary Smith",
email:"mary@contoso.com",
roles:[],
createdOn: now,
links: [
{ rel: "self",
href: SERVER_ADDR+"/user/Mary",
},
{ rel: "edit",
href: SERVER_ADDR+"/user/Mary",
},
{ rel: "collection",
href: SERVER_ADDR+"/user"
},
{ rel: "psidi:user-messages",
href: SERVER_ADDR+"/message?user=Mary",
},
{ rel: "psidi:user-photo",
href: SERVER_ADDR+"/user/Mary/photo",
},
],
};

40. {
"a11": {
"id": "a11",
"text": "Sample one",
"senderId": "Mary",
"createdOn": "2014-12-17T18:35:00.149Z",
"updatedOn": "2014-12-17T18:35:00.149Z",
"links": [
{
"rel": "self",
"href": "http://localhost:3001/message/a11"
},
{
"rel": "edit",
"href": "http://localhost:3001/message/a11"
},
{
"rel": "collection",
42
ISEP/IPP
GET
http://localhost:3001/messag
e

41. 43
ISEP/IPP
GET
http://localhost:3001/message/a1
1

42. 44
ISEP/IPP
GET http://localhost:3001/user

43. 45
ISEP/IPP
GET
http://localhost:3001/user/Mary

44. REPRESENTATION VS
RESOURCE
Resource (e.g., table
record)
{
id: PRIMARY_KEY
text: "Sample one",
senderId: FOREIGN_KEY TO
“users”
createdOn: now,
updatedOn: now,
};
Resource
Representation
{
text: "Sample one",
createdOn: now,
updatedOn: now,
links: [
{ rel: "self",
href: SERVER_ROOT+"/message/a1", // URI
},
{ rel: "edit",
href: SERVER_ROOT+"/message/a1", // URI
},
{ rel: "collection",
href: SERVER_ROOT+"/message“ // URI
},
{ rel: "psidi:user",
href: SERVER_ROOT+"/user/Mary", // URI
title: "Mary Smith“
}
],
};
46

45. CONTINUE THE ROAD TO
HYPERMEDIA
Several things are missing:
Reuse generic collection media type, e.g.,
Collection+JSON, OData
Reuse existing media types and microformats, e.g.,
hCard
“New item” template
Search templates, e.g., OpenSearch
Photo subresource: information + media
47
ISEP/IPP

46. CLOSINGS
48

47. 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
49
ISEP/IPP

48. SUGGESTED READINGS
Fielding, R. “REST APIs must be hypertext-driven”.
http://roy.gbiv.com/untangled/2008/rest-apis-must-
be-hypertext-driven
Atom/AtomPub.
http://bitworking.org/projects/atom/rfc5023.html
Collection+JSON media type.
http://amundsen.com/media-types/collection/
OData. http://www.odata.org/
OpenSearch. http://www.opensearch.org/Home
HTTP PATCH. http://tools.ietf.org/html/rfc5789
50
ISEP/IPP

49. PROGRAMAÇÃO DE
SISTEMAS
DISTRIBUIDOS
Paulo Gandra
de Sousa
pag@isep.ipp.
pt