Principal API Architect Mike Amundsen presented this talk at QConn New York 2013.
Hypermedia APIs are getting some buzz. But what are they, really? What is the difference between common URI-based CRUD API designs and hypermedia-style APIs? How do you implement a hypermedia API and when does it make sense to use a hypermedia design instead of a CRUD-based approach? Based on the Mike Amundsen's multi-part InfoQ article series of the same name, this fast paced, hands-on four-hour workshop shows attendees how to design a hypermedia style API, how to implement a server that supports varying hypermedia responses, and how to build clients that can take advantage of hypermedia. Additional time will be spent exploring when clients break and how reliance on hypermedia can reduce the need for re-coding and re-deploying client applications while still supporting new features in the API. Hands-on labs include authoring a hypermedia format for your API, designing server-side components that can emit hypermedia responses, and deciding on which client-side style of hypermedia fits best for your needs. A final challenge will be to update the server-side responses with new features that do not break existing hypermedia clients.
Powerful Google developer tools for immediate impact! (2023-24 C)
Designing & Implementing Hypermedia APIs – Mike Amundsen, Principal API Architect, Layer 7
1. 1
Designing and Implementing Hypermedia APIs
QCon New York 2013
Mike Amundsen,
Principal API Architect
Layer 7 Techologies
@mamund
#HyperQCon
2. 2
Mike Amundsen
Author, Web Architect, Presenter
Principal API Architect
Building Hypermedia APIs with HTML5 and Node
RESTful Web APIs (Richardson, Amundsen, Ruby)
3. 3
Agenda
Hypermedia – the Short Story (15:00)
Designing Hypermedia APIs (10:00 )
Hack a Hypermedia API (30:00)
Implementing Hypermedia Servers (10 :00)
Hack a Hypermedia Server (45:00)
Building Hypermedia Clients (10:00)
Hack a Hypermedia Client (45:00)
Now What? (15:00)
4. 4
Reminders
Bells & Whistles Off
Feel free to stretch, move about as needed
Ask Questions
Enjoy the Session
8. 8
Vannevar Bush
Memex, 1945
Key project leader on the Manhattan Project to build the first nuclear
bomb.
“ A memex …is an enlarged intimate supplement to … memory.”
“With one item in its grasp, [the mind] snaps instantly to the next that is
suggested by the association of thoughts, in accordance with some
intricate web of trails carried by the cells of the brain.”
9. 9
Douglas Engelbart
Computer mouse, 1965
Key to creating the ARPANET while at Stanford Research, Institue (SRI).
“Augmenting Human Intellect”, 1962
“[A] new and systematic approach to improving the intellectual effectiveness of
the individual human being … One of the tools that shows the greatest
immediate promise is the computer.”
10. 10
Ted Nelson
Hypertext, 1963
Identified and popularized early “cyber-culture” in 1979 book “Computer
Lib/Machine Dreams”
“If computers are the wave of the future, displays are the surfboards.”
11. 11
James J. Gibson
“The Ecological Approach to Visual Perception” (1986)
Coined the term “affordance”
Environments provide niches of appropriate affordances
Animals survive/thrive when they can exploit the affordances in their niche
“An affordance is a quality of an object, or an environment, which allows an
individual to perform an action.”
12. 12
Donald Norman
The Design of Everyday Things, 1988
Action Lifecycle, Seven Stages of Action
“In the world” and “In the head”
“Simplification is as much in the mind as it is in the device.”
“Design is really an act of communication.”
13. 13
Tim Berners-Lee
Tim Berners-Lee @ CERN 1980
ENQUIRE in 1984 (hypertext database)
Information Mgmt: A Proposal to CERN in 1989
HTTP (1992), HTML (1993), RDF (2004)
“A way to link and access information of various kinds as a web of nodes in which the
user can browse at will.”
14. 14
Roy T. Fielding
Architectural Styles and the
Design of Network-based Software Architectures, 2000
Created “REST”
Key in the startup and operation of the “Apache Foundation”
Representations and Hypermedia
“A resource is not the thing that is transferred across the wire or picked up off the
disk or seen from afar while walking your dog. Each of those is only a representation.
Do I think of a different identifier every time I see my dog, or do I simply think of my
dog as one identity and experience many representations of that identity over time
(and on into memory and imagination)?
32. 32
H-Factors
A collection of H-Factors is called a Hypermedia Type
By identifying H-Factors, you discover the “Hypermedia signature” of media type.
35. 35
Three Pillars of Hypermedia Design
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.
36. 36
Three Pillars of Hypermedia Design
Structure Semantics
How you communicate the layout of the response
Simple structures:
- text/csv
- application/xml
- application/json
Advanced structures
- text/html
- application/atom+xml
- application/vnd.hal+json
- application/vnd.collection+json
37. 37
Three Pillars of Hypermedia Design
Protocol Semantics
How you communicate the possible actions in the response
Simple actions:
- HTML.A
- HTML.IMG
- HTML.LINK
Advanced actions:
- HTML.FORM@get
- HTML.FORM@post
- ATOM.LINK@edit
- collection.queries.link@data[]
38. 38
Three Pillars of Hypermedia Design
Domain Semantics
How you communicate the domain-specific details in the response
Simple domain-specifics:
- MAZE: collection, cell
- VOICEXML: assign, transfer, disconnect,
- ATOM: feed, entry, content
Advanced domain-specifics
- HTML: @id, @name, @class, @rel
- CJ: @id, @name, @value, @href
- HAL: @rel, @name
39. 39
Three Pillars of Hypermedia Design
On the Web, media types don’t define a solution,
they describe a problem domain
40. 40
Three Pillars of Hypermedia Design
The more descriptive the media type,
the easier it is to talk about the problem.
48. 48
Designing Hypermedia APIs
Let’s map the actions to (at least) one Web protocol…
We could use HTTP, WebSockets, XMPP…
But, of course, we’ll use HTTP today.
49. 49
Protocol
Map eight actions:
- add, update, remove,
read, list, filter,
assign, unassign
To four HTTP methods:
- GET, POST,
PUT, DELETE.
72. 72
Representation Layer
Representation happens in the Connector
HTTP supports content negotiation
- Accept
- Content-Type
Differing clients (user-agents) === differing representations
- Desktop
- Browser
- Tablet
- Smartphone
Be prepared to support multiple representations
73. 73
Implementing Hypermedia Servers
Storage
Handles direct access to stored content (if any)
Database (MySQL, SQLServer, Oracle, CouchDB, Mongo, etc.)
File system (Local File I/O)
External Service (Salesforce, Amazon, Azure, etc.)
In-Memory (memcacheD, etc.)
Advice for this event:
- Keep it simple
- Use in-memory array for starter, add perm storage later
- Use existing APIs (see listing today)
74. 74
Implementing Hypermedia Servers
Components
Handles business rules and any processing/computing, etc.
Validate data/objects
Create any defaults or related data/objects
Enforce data integrity on writes
Enforce ACLs on reads/writes (skip for today)
Advice for this event:
- Keep it simple
- Consider read-only for today
- Use existing APIs (see listing today)
75. 75
Implementing Hypermedia Servers
Representation
Handles converting internal objects into external media type
*NOT* a serializer
Convert object graph into list/items
Include protocol affordances (links & forms)
Maps domain-specifics to appropriate elements/attributes/properties
Advice for this event:
- Keep it simple
- Consider using an existing hypermedia type
- Use existing APIs (see listing today)
76. 76
Implementing Hypermedia Servers
Routing
Handles incoming requests, routes to appropriate method/handler
Thin veneer behind API
NOT a direct wrapper for components
Converts request URL parts into arguments
Usually handles call to representation service for responses
MAY handle caching directives (skip for today)
Advice for this event:
- Keep it simple
- Consider a very simple URL routing pattern (/{thing}/{id})
- Use existing APIs (see listing today)
82. 82
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.
83. 83
Some things to keep in mind…
Hypermedia clients are based on the “Action Lifecycle”
84. 84
Some things to keep in mind…
http://en.wikipedia.org/wiki/Human_action_cycle
88. 88
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.
89. 89
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.
90. 90
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.
99. 99
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
100. 100
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
101. 101
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.
103. 103
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.
104. 104
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.
105. 105
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/
106. 106
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”
114. 114
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
115. 115
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
116. 116
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.
118. 118
Summary : Building Hypermedia Clients
Hypermedia clients for humans (FHC)
- 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.
Hypermedia clients for machines (AHC)
- 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.
Hypermedia clients are based on the “Action Lifecycle”
Hypermedia clients’ memories usually last for a single request/response cycle.
120. 120
Now What?
Hypermedia goes back more than ½ a century
Remember the H-Factors (LO, LE, LT, LI, LN, CR, CU, CM, CL)
Always solve for the Three Pillars (Structure, Protocol, Domain)
Servers have:
- Components (Storage & Processing)
- Connectors (Routing & Representation)
Clients have:
- No long-term memory
- Support for Action Lifecycle
- FHCs (for humans)
- ACHs (for machines)