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
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
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
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
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
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
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
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
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
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
An API that is based on the notion of hypermedia
Message payload is of an hypermedia-enabled media type
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]
LE: embed the contente of the link target with the current content
LO: traverse the link
LT: traverse the link but construct the link with the template
LI: submit content using idempotent request (e.g., PUT, DELETE)
LN: submit content using non-idepontent request (e.g., POST)
The possible metadata elements (and their values) can vary between supported
protocols (FTP, HTTP, etc.) as does the details for communicating this link metadata.
For example, in HTTP, this is accomplished through HTTP Headers. Regardless of the
mechanism, control factors fall into four categories: Read, Update, Method, and Link
Annotation.