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.

1. 1
Implementing Hypermedia Clients:
It’s Not Rocket Science
 Mike Amundsen,
Principal API Architect
Layer 7 Technologies
@mamund

2. 2
Mike Amundsen
 Author, Web Architect, Presenter
 Principal API Architect
 “Help people build great APIs for the Web.”
 Part of the API Academy

3. 3
API Academy Team

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.

8. 8
HYPERMEDIA: A SHORT HISTORY

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."

16. 16
HYPERMEDIA ANATOMY

17. 17
H-Factors
Analyzing Media Types

18. 18
H-Factors
Analyzing Media Types

19. 19
H-Factors
Analyzing Media Types

20. 20
H-Factors
 There are five LINK Factors
(LO, LE, LT, LI, LN)
 There are four CONTROL Factors
(CR, CU, CM, CL)

21. 21
H-Factors
 There are five LINK Factors
(LO, LE, LT, LI, LN)
 There are four CONTROL Factors
(CR, CU, CM, CL)

22. 22
H-Factors
Linking
Outbound Links (LO)

23. 23
H-Factors
Linking
Outbound Links (LO)
Embedded Links (LE)

24. 24
H-Factors
Linking
Outbound Links (LO)
Embedded Links (LE)
Templated Links (LT)

25. 25
H-Factors
Linking
Outbound Links (LO)
Embedded Links (LE)
Templated Links (LT)
Idempotent Links (LI)

26. 26
H-Factors
Linking
Outbound Links (LO)
Embedded Links (LE)
Templated Links (LT)
Idempotent Links (LI)
Non-Idempotent Links (LN)

27. 27
H-Factors
 There are five LINK Factors
(LO, LE, LT, LI, LN)
 There are four CONTROL Factors
(CR, CU, CM, CL)

28. 28
H-Factors
Control
Request Controls (CR)

29. 29
H-Factors
Control
Request Controls (CR)
Update Controls (CU)

30. 30
H-Factors
Control
Request Controls (CR)
Update Controls (CU)
Method Controls (CM)

31. 31
H-Factors
Control
Request Controls (CR)
Update Controls (CU)
Method Controls (CM)
Link Controls (CL)

32. 32
H-Factors
 A pre-defined collection of H-Factors is called a “Media Type”
 Each media type has it’s own “H-Factor” signature.

33. 33
A HYPERMEDIA TYPE

34. 34
On the Web, media types don’t define a solution,
they describe a problem domain

35. 35
The more descriptive the media type,
the easier it is to talk about the problem

36. 36
What problem domain is described by
Plain Text?
CSV?
XML?
JSON?
YAML?
Atom?
HTML?
VoiceXML?

37. 37
Let’s describe the Class Scheduling domain…

38. 38
Let’s describe the Class Scheduling domain…
and let’s keep it real simple today.

39. 39
application/vnd.apiacademy-scheduling+xml

40. 40
Domain
 Eleven data elements:
- courseCapacity,
courseDescription,
courseId, courseName,
scheduleId, scheduleSlot,
studentId, studentName,
studentStanding,
teacherId, teacherName
 Eight actions:
- add, update, remove,
read, list, filter, assign,
unassign
 Five identifiers:
- home, course, student,
teacher, schedule

41. 41
Let’s map the actions to (at least) one Web protocol…

42. 42
Let’s map the actions to (at least) one Web protocol…
We could use HTTP, WebSockets, XMPP…

43. 43
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.

44. 44
Protocol
 Map eight actions:
- add, update, remove,
read, list, filter,
assign, unassign
 To four HTTP methods:
- GET, POST,
PUT, DELETE.

45. 45
Let’s document the possible data elements
for each action, too.

46. 46
Data elements with actions…

47. 47
Finally, let’s design a single message
that can carry all that information…

48. 48
Structure
 Nine Elements
- root, actions, link, list,
item, template, display,
data, error
 Six Attributes
- href, name, action,
prompt, value, embed
 Four Data Types
- ID, URI, TEXT,
BOOLEAN

49. 49
Note there are three key aspects to each message design…

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.

51. 51
Now let’s see some examples…

52. 52

53. 53
And magically a server appears….
(we’ll cover server implementation some other time).

54. 54
Sample response from a compliant server

55. 55
HYPERMEDIA FOR HUMANS

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

59. 63
Some things to keep in mind…
Oh!, I almost forgot…

60. 64
Hypermedia clients
Typically hypermedia clients have almost no long-term memory.

61. 65
Hypermedia clients
Typically hypermedia clients have almost no long-term memory.
Hypermedia clients’ memories last for a single request/response 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.

65. 69
Process the structure semantics

66. 70
Process the structure semantics

67. 71
Process the structure semantics

68. 72
Process protocol semantics

69. 73
Process protocol semantics

70. 74
Process protocol semantics

71. 75
Process domain semantics

72. 76
Process domain semantics

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.

76. 80
HYPERMEDIA FOR MACHINES

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”

80. 84
Maze+XML Media Type

81. 85
Maze+XML FHC

82. 86
The Maze+XML AHC

83. 87
“Teach” AHC about mazes

84. 88
Process the structure semantics

85. 89
Process the protocol semantics

86. 90
Process the domain semantics

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.

90. 94
SUMMARY

91. 95
History
Hypermedia was there from “day one” but many times we still don’t use it
on the Web.

92. 96
Anatomy
H-Factors give us a way to look at hypermedia separately and design
messages according to our needs.

93. 97
Interaction
Building hypermedia clients means relying on Norman’s “Action Lifecycle”

94. 98
Implementation
Web clients must always be able to handle three type of semantics:
Structure, Protocol, Domain

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.

97. 101
Remember…

98. 102
It may be hard work, but it’s not
Rocket Science.
Thank you!

99. 103
Implementing Hypermedia Clients:
It’s Not Rocket Science
 Mike Amundsen,
Principal API Architect
Layer 7 Technologies
@mamund