Coding hypermedia clients need not be ugly nor complicated. This session shows you how to write clean, adaptive code that responds to changes in data and workflow requirements over time. This session covers the truth (both good and bad) about hypermedia client coding and includes examples of several client models that handle evolvable Hypermedia APIs without sacrificing user experience or requiring Herculean effort on the part of developers.
2. 2
Mike Amundsen
Author, Web Architect, Presenter
Principal API Architect
“Help people build great APIs for the Web.”
Part of the API Academy
4. 4
Mike Amundsen
Building Hypermedia APIs with HTML5 and Node (2011)
Focus on hypermedia theory and practice
Examples for both humans and M2M scenarios
Guidance on designing and registering media types
5. 5
Mike Amundsen
RESTful Web APIs w/ Leonard Richardson and Sam Ruby (August 2013)
Good for both introduction and in-depth REST skills
Emphasis on protocol-level hypermedia
Focus on closing the app-level semantic gap
Guidance on creating machine-readable documentation
Sample Galley proof at the O’Reilly booth this week.
6. 6
Mike Amundsen
Office Hours in the Exhibit Hall
- Today – right after this session
Book signing at the O’Reilly Booth
- Today at 5:45P
Available here throughout the week – come up and say ‘Hi!’
@mamund on Twitter
7. 7
It may be hard work, but it’s not
Rocket Science.
9. 9
Vannevar Bush
“As We May Think”, July 1945
“Consider a future device for individual use, which is a sort
of mechanized private file and library. It needs a name, and
to coin one at random, "memex" will do.”
10. 10
Douglas Engelbart
“Augmenting Human Intelligence”, 1962
oNLineSystem (NLS), 1968
Inventor of the “mouse”
“We refer to a way of life in an integrated
domain where hunches, cut-and-try,
intangibles, and the human "feel for a
situation" usefully co-exist with powerful
concepts, streamlined terminology and
notation, sophisticated methods, and high-
powered electronic aids.”
11. 11
Theodor Nelson
“Computer Lib/Dream Machines”, 1974
Coined “hypertext”
Father of the “Cyber-culture”
“ If computers are the wave of the future, displays are the
surfboards.”
12. 12
Roy T. Fielding
“Architectural Styles and the Design of Network-based
Software Architectures”, 2000
Identified REST architectural style
"Hypermedia is defined by the presence of application
control information embedded within, or as a layer above,
the presentation of information. Distributed hypermedia
allows the presentation and control information to be stored
at remote locations."
13. 13
Roy T. Fielding
“Hypermedia is defined by the presence of
application control information embedded
within, or as a layer above, the presentation
of information."
14. 14
Roy T. Fielding
“Hypermedia is defined by the presence of
application control information embedded
within, or as a layer above, the presentation
of information."
15. 15
Roy T. Fielding
“Hypermedia is defined by the presence of
application control information embedded
within, or as a layer above, the presentation
of information."
50. 50
Three Semantic Layers for a Media Type
Structure Semantics (XML, JSON, YAML, etc.)
Protocol Semantics (HTTP, WS, FTP, etc.)
Application Domain Semantics (students, courseName, scheduleId, etc.)
All Web apps MUST support these somehow. What’s not in the
message, is in the source code instead.
56. 56
What is a Hypermedia for Humans client?
A client that is able to
determine possible protocol-level choices at runtime
using only the links and forms in the message itself as a guide.
57. 61
Some things to keep in mind…
Hypermedia clients are based on the “Action Lifecycle”
58. 62
Some things to keep in mind…
http://en.wikipedia.org/wiki/Human_action_cycle
62. 66
Hypermedia clients
Typically hypermedia clients have almost no long-term memory.
Hypermedia clients’ memories last for a single request/response cycle.
Clients MAY save a past response, parse it, store it, and recall it later.
63. 67
Faithful Hypermedia Clients (FHCs)
FHCs simply pass along whatever the server returns; usually to a human.
FHCs MAY make some decisions on how to display the returned representation
FHCs only need a starting URL and a (human) driver.
64. 68
Guide for implementing an FHC
Process the structure semantics in order to render view
Process the protocol semantics in order to support available transitions
Process the domain semantics in order to inform human of choices & results.
73. 77
Summary for the Class Schedule FHC
Structure Semantics
- Take advantage of client-side XSLT
- Build XSL processor for vnd.apiacademy-scheduling+xml
- 120 lines of XSLT
Protocol Semantics
- Take advantage of XmlHttpRequest
- Provide a single JS file that “understands” vnd.apiacademy-scheduling+xml
- 130 lines of JS
Domain Semantics
- Use CSS to hide/show things for humans (.id, .dateCreated)
- 130 lines of CSS
74. 78
Advantages of hypermedia clients for humans
Flexibility to support a wide range of non-breaking domain-level changes
- Adding new display & input fields
- Adding new resources/pages
- Adding new link and form options (not new protocol options)
- Changes in access control rules is “automatic” (No access? No controls!)
Ability to separate “parsing” from “display”
- Most hypermedia types keep clear separation between processing and display
- Can make it easier to handle negotiations
between server devs and UI devs
Ability to customize engines for devices
- Same hypermedia message can be handled
differently on each device, when applicable
- Increased freedom for UI devs
75. 79
Drawbacks of hypermedia clients for humans
SoC can mean extra work for clients
- Need to keep structure, protocol, domain clearly separated
Possibility of changes in server can limit UI options
- UI devs must plan for change (even before it happens)
Anything short of FHC risks client adaptability
- If client determines what to display, new fields will not appear.
- If client determines what transitions to support
and in what order they appear, changes (add/
move forms & links) may break the client.
If the message format is unstable (breaking
changes occurring), FHCs have no real
advantage over one-off client coding.
77. 81
What is a hypermedia machine client?
A client that is able to
process responses,
locate protocol actions, and
make domain-level choices at runtime
using only the links and forms in the message itself as a guide.
78. 82
Agent Hypermedia Clients (AHCs)
AHCs can process all three levels of messages:
- Structure
- Protocol
- Domain
AHCs MUST be able to make decisions on their own
AHCs need only a starting URL
http://xkcd.com/695/
79. 83
Guide for implementing an AHC
Process the structure semantics in order to know what’s “there”
Process the protocol semantics in order to know what’s possible
Process the domain semantics in order to make an informed choice
The machine is in charge of the complete “Action Lifecycle”
87. 91
Summary for Maze+XML AHC
Structure Semantics
- XML DOM Parser + recognizing five elements (maze, collection, item,cell, link)
Protocol Semantics
- Support maze:link (H-factor=LO, HTTP.GET)
Domain Semantics
- Understand “wall-following” and choose between “start”, “north”, “south”, “east”,
west”, and “exit”
150 lines of NodeJS code
88. 92
Advantages of hypermedia clients for machines
Ability to hand off tedious work to “smart” machine
Using “generic” media types makes it possible to use the same client code for
several different tasks/projects
Coding new tasks gets faster over time since the baseline code already exists
Simple modifications in the server (order to items in message) don’t break clients
89. 93
Drawbacks of hypermedia clients for machines
Making machines “smart” takes time, esp. for non-trivial tasks
Some changes in message can break clients (missing transitions, new fields, etc.)
Some unsafe operations (POST/PUT/DELETE) may need human intervention
anyway.
Not many “machine-friendly” hypermedia types yet.
95. 99
Hypermedia for Humans
FHCs (faithful renders) add flexibility for future non-breaking changes by
sacrificing some freedom in the initial design (plan for the “unexpected”)
96. 100
Hypermedia for Machines
AHCs (agents) make it possible to use a “generic” format to
handle tedious tasks as long as the machine can be
“smart enough” for the domain.