Video and slides synchronized, mp3 and slide download available at http://bit.ly/Zwa0x9. Mike Amundsen discusses the theory behind building hypermedia APIs combined with real life cases exemplifying the successes and failures of such an endeavor. Filmed at qconsf.com. Mike Amundsen is Principal API Architect for Layer 7 Technologies, helping people build great APIs for the Web. An internationally known author and lecturer, Mike travels throughout the US and Europe consulting and speaking on distributed network architecture, Web application development, Cloud computing, and other subjects. He has more than a dozen books to his credit.

1. Layer 7 Confidential 1
Mike Amundsen
The Costs and Benefits of
Building Hypermedia APIs
(with Node.js)

2. InfoQ.com: News & Community Site
• 750,000 unique visitors/month
• Published in 4 languages (English, Chinese, Japanese and Brazilian
Portuguese)
• Post content from our QCon conferences
• News 15-20 / week
• Articles 3-4 / week
• Presentations (videos) 12-15 / week
• Interviews 2-3 / week
• Books 1 / month
Watch the video with slide
synchronization on InfoQ.com!
http://www.infoq.com/presentations
/Building-Hypermedia-API

3. Presented at QCon San Francisco
www.qconsf.com
Purpose of QCon
- to empower software development by facilitating the spread of
knowledge and innovation
Strategy
- practitioner-driven conference designed for YOU: influencers of
change and innovation in your teams
- speakers and topics driving the evolution and innovation
- connecting and catalyzing the influencers and innovators
Highlights
- attended by more than 12,000 delegates since 2007
- held in 9 cities worldwide

4. Layer 7 Confidential 2
Mike Amundsen
Author
Presenter
Software Explorer
Principal API Architect

5. Layer 7 Confidential 3
OK, let’s get started…

6. Layer 7 Confidential 4
Theonia
"a looking at, viewing, beholding”

7. Layer 7 Confidential 5
Theory
"a looking at, viewing, beholding”

8. Layer 7 Confidential 6
Praxis
“doing”

9. Layer 7 Confidential 7
Practice
“doing”

10. Layer 7 Confidential 8
First, a lesson to remember
from Donald Norman…

11. Layer 7 Confidential 10
Affordances
“The value of a well-designed object,
Is when it has such a rich set of affordances,
That the people who use it,
Can do things with it,
That the designer never imagined.”
- Donald Norman

12. Layer 7 Confidential 11
Affordances
“The value of a well-designed object,
Is when it has such a rich set of affordances,
That the people who use it,
Can do things with it,
That the designer never imagined.”
- Donald Norman

13. Layer 7 Confidential 12
Affordances
“The value of a well-designed object,
Is when it has such a rich set of affordances,
That the people who use it,
Can do things with it,
That the designer never imagined.”
- Donald Norman

14. Layer 7 Confidential 13
Affordances
“The value of a well-designed object,
Is when it has such a rich set of affordances,
That the people who use it,
Can do things with it,
That the designer never imagined.”
- Donald Norman

15. Layer 7 Confidential 14
Affordances
“The value of a well-designed object,
Is when it has such a rich set of affordances,
That the people who use it,
Can do things with it,
That the designer never imagined.”
- Donald Norman

16. Layer 7 Confidential 15
Some background…

17. Layer 7 Confidential 16
Affordances
The foundation for perception is ambient,
ecologically available information.
Affordances are all "action possibilities" latent in
the environment.
Theory of Affordances, 1979
- James J. Gibson

18. Layer 7 Confidential 17
Seven Stages of Action
Affordances
The Design of Everyday Things, 1988
- Donald Norman

19. Layer 7 Confidential 18
Affordances
Knowledge (“head” vs. “world”)
April 17, 2012 APIs to Affordances : WS-REST 2012 18
Property
Knowledge in the
World
Knowledge in the Head
Learning
Learning not required.
Interpretation
substitutes for learning.
How easy it is to
interpret information is
the world depends
upon how well it
exploits natural
mappings and
constraints.
Requires learning, which
can be considerable.
Learning is made easier if
there is meaning of
structure to the material (or
if there is a good mental
model).
Efficiency
of use
Tends to be slowed up
by the need to find and
interpret the external
information.
Can be very efficient
Ease of use
at first
encounter
High Low

20. Layer 7 Confidential 19
Affordances
"Hypermedia is defined by the presence of application
control information embedded within, or as a layer above,
the presentation of information“ (2001)
“When I say [Hypermedia], I mean the simultaneous
presentation of information and controls such that the
information becomes the affordance through which the user
obtains choices and selects actions” (2008)
Architectural Styles and the Design
of Network-based Software, 2001
- Roy T. Fielding

21. Layer 7 Confidential 20
Affordances
"Hypermedia is defined by the presence of application
control information embedded within, or as a layer above,
the presentation of information“ (2001)
“When I say [Hypermedia], I mean the simultaneous
presentation of information and controls such that the
information becomes the affordance through which the user
obtains choices and selects actions” (2008)
Architectural Styles and the Design
of Network-based Software, 2001
- Roy T. Fielding

22. Layer 7 Confidential 21
Affordances
Affordances
make
Hypermedia
possible.

23. Layer 7 Confidential 22
Affordances
Hypermedia
can provide a
Rich Set of Affordances

24. Layer 7 Confidential 23
Maze+XML
Design #1:
A big pile of Affordances

25. Layer 7 Confidential 24
Maze+XML
Maze+XML media type
First design in late 2010, registered w/ IANA 2011
“…an XML data format for sharing maze state information
between clients and servers. It can be used to implement
simple mazes, adventure games, and other related data.”
Read-only navigational links
Nine link identifiers:
collection, maze, start, exit, current,
north, south, east, west

26. Layer 7 Confidential 25
Maze+XML
Message

27. Layer 7 Confidential 26
Maze+XML
Server

28. Layer 7 Confidential 27
Maze+XML
Client

29. Layer 7 Confidential 28
Maze+XML
Client

30. Layer 7 Confidential 29
Maze+XML
Client

31. Layer 7 Confidential 30
Maze+XML
Client Code

32. Layer 7 Confidential 31
Maze+XML
In the wild…

33. Layer 7 Confidential 32
Maze+XML
Darrel Miller
“A good example of using link relations to convey
domain specific semantics.”
“Has been a good test bed for trying to develop a UI
transparently that tracks the state of the user agent as it
navigates between representations.”

34. Layer 7 Confidential 33
Maze+XML
Darrel Miller – C#

35. Layer 7 Confidential 34
Yannick Loiseau
“I can say that a non-restful architecture would have been a
lot harder to deal with in bash, because hypermedia
obviously made the maze exploration really easy”
“I think that Link headers would be even
easier to deal with…”
Maze+XML

36. Layer 7 Confidential 35
Yannick Loiseau - Python
Maze+XML

37. Layer 7 Confidential 36
Yannick Loiseau - Bash
Maze+XML

38. Layer 7 Confidential 37
Maze+XML
Characteristics
- Read-Only navigational links
- Limited set of identifiers
- Domain specific
Benefits
- Simple, direct design
- Easy to create servers/clients
- M2M works when algorithm is available
Costs
- Limited reach
- M2M clients challenge evolvability

39. Layer 7 Confidential 38
H-Factors
“Pardon me, did you say ‘links’?”

40. Layer 7 Confidential 39
“The H Factor of a media-type is a measure of the
level of hypermedia support within that media-type.”
“H Factor values can be used to compare and
contrast media types in order to aid in selecting the
proper media-type(s) for your
implementation.”
H-Factors
REST: From Research to Practice :
Hypermedia Types, 2011
- Mike Amundsen

41. Layer 7 Confidential 40
H-Factors
Analyzing Media Types

42. Layer 7 Confidential 41
H-Factors
Analyzing Media Types

43. Layer 7 Confidential 42
H-Factors
Analyzing Media Types

44. Layer 7 Confidential 43
H-Factors
There are five LINK Factors
(LO, LE, LT, LI, LN)
There are four CONTROL Factors
(CR, CU, CM, CL)

45. Layer 7 Confidential 44
H-Factors
There are five LINK Factors
(LO, LE, LT, LI, LN)
There are four CONTROL Factors
(CR, CU, CM, CL)

46. Layer 7 Confidential 45
H-Factors
Linking
Outbound Links (LO)

47. Layer 7 Confidential 46
H-Factors
Linking
Outbound Links (LO)
Embedded Links (LE)

48. Layer 7 Confidential 47
H-Factors
Linking
Outbound Links (LO)
Embedded Links (LE)
Templated Links (LT)

49. Layer 7 Confidential 48
H-Factors
Linking
Outbound Links (LO)
Embedded Links (LE)
Templated Links (LT)
Idempotent Links (LI)

50. Layer 7 Confidential 49
H-Factors
Linking
Outbound Links (LO)
Embedded Links (LE)
Templated Links (LT)
Idempotent Links (LI)
Non-Idempotent Links (LN)

51. Layer 7 Confidential 50
H-Factors
There are five LINK Factors
(LO, LE, LT, LI, LN)
There are four CONTROL Factors
(CR, CU, CM, CL)

52. Layer 7 Confidential 51
H-Factors
Control
Request Controls (CR)

53. Layer 7 Confidential 52
H-Factors
Control
Request Controls (CR)
Update Controls (CU)

54. Layer 7 Confidential 53
H-Factors
Control
Request Controls (CR)
Update Controls (CU)
Method Controls (CM)

55. Layer 7 Confidential 54
H-Factors
Control
Request Controls (CR)
Update Controls (CU)
Method Controls (CM)
Link Controls (CL)

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

57. Layer 7 Confidential 56
H-Factors
H-Factors document
the Affordances
of the
Media Type

58. Layer 7 Confidential 57
H-Factors
“OK, media types, affordances, I see…

59. Layer 7 Confidential 58
Collection+JSON
Design #2:
A read/write hypermedia type

60. Layer 7 Confidential 59
Collection+JSON
Collection+JSON media type
First designs in early 2011, registered w/ IANA mid 2011
“…a JSON-based read/write hypermedia-type designed to
support management and querying of simple collections.”
It’s Atom w/ LT + templated writes
Very limited link identifiers
- collection, item, templates, query

61. Layer 7 Confidential 60
Message
Collection+JSON

62. Layer 7 Confidential 61
Message
Collection+JSON

63. Layer 7 Confidential 62
Message
Collection+JSON

64. Layer 7 Confidential 63
Message
Collection+JSON

65. Layer 7 Confidential 64
Message
Collection+JSON

66. Layer 7 Confidential 65
Server
Collection+JSON

67. Layer 7 Confidential 66
Server
Collection+JSON

68. Layer 7 Confidential 67
Server
Collection+JSON

69. Layer 7 Confidential 68
Client Code
Collection+JSON

70. Layer 7 Confidential 69
Client Code
Collection+JSON

71. Layer 7 Confidential 70
Client Code
Collection+JSON

72. Layer 7 Confidential 71
Client App
Collection+JSON

73. Layer 7 Confidential 72
Client App
Collection+JSON

74. Layer 7 Confidential 73
Collection+JSON
In the wild…

75. Layer 7 Confidential 74
Collection+JSON
Nokia Research - Live Mixed Reality - Vlad Stribu
“[Collection+JSON] … allows us to develop authoring tools
that have the ability to self-adapt the user interface to the
usage context.”

76. Layer 7 Confidential 75
Collection+JSON
Nokia Research - Live Mixed Reality - Vlad Stribu
“Collection+JSON was close enough to what we were
looking for…”
“Most important factor that influenced our decision was the
community around this format…”

77. Layer 7 Confidential 76
Collection+JSON
CloudApp – Larry Marburger
“CloudApp allows you to share images, links, music, videos
and files.”
“[Due to developer team changes] we had some setbacks
with the Mac app and subsequently the API. We just started
working with another developer who's making amazing
progress.”

78. Layer 7 Confidential 77
Collection+JSON
ember.js – Yehuda Katz
“A framework for creating ambitious applications.”
“By default, it's somewhat repetitive, but that can be
addressed…”
“It was straight-forward to extend it with features I needed”
“I am starting to feel like with the number of extensions, I
should consider [creating] my own media type.”

79. Layer 7 Confidential 78
Collection+JSON
Characteristics
- Read/Write w/ Templates
- Small set of link identifiers
- General “List Domain” handler
Benefits
- Limited design means simple parser
- Servers easy, clients harder
- Built-in support for custom domain annotations
Costs
- Domain mapping is more difficult
- M2M clients limited to pre-declared vocabulary

80. Layer 7 Confidential 79
Affordance Aspects
“So, are all affordances essentially
the same?”

81. Layer 7 Confidential 80
Affordance Aspects
“For the purposes of applying affordances to
hypermedia, there are four important aspects
to consider”

82. Layer 7 Confidential 81
Affordance Aspects
Safe
The HTTP protocol supports a number of "safe"
actions such as HEAD, and GET.

83. Layer 7 Confidential 82
Affordance Aspects
Safe
The HTTP protocol supports a number of "safe"
actions such as HEAD, and GET.
The HTTP methods PUT, POST, and DELETE are
categorized as "unsafe" actions.

84. Layer 7 Confidential 83
Affordance Aspects
Idempotent
When an HTML:FORM element has the METHOD
property set to "get" it represents an idempotent
action.

85. Layer 7 Confidential 84
Affordance Aspects
Idempotent
When an HTML:FORM element has the METHOD
property set to "get" it represents an idempotent
action.
When the same property is set to "post" the
affordance represents a non-idempotent action.

86. Layer 7 Confidential 85
Affordance Aspects
Mutability
HTML:FORM affords mutability

87. Layer 7 Confidential 86
Affordance Aspects
Mutability
HTML:FORM affords mutability
HTML:LINK is immutable

88. Layer 7 Confidential 87
Affordance Aspects
Transclusion
HTML:IMG affords transclusion

89. Layer 7 Confidential 88
Affordance Aspects
Transclusion
HTML:IMG affords transclusion
HTML:A does not

90. Layer 7 Confidential 89
Affordance Aspects
However, this single affordance is not
very usable.

91. Layer 7 Confidential 90
Affordance Aspects
Media types
should be
usable

92. Layer 7 Confidential 91
Affordance Aspects
Messages
should be
usable

93. Layer 7 Confidential 92
Affordance Aspects
APIs
should be
usable

94. Layer 7 Confidential 93
ALPS for HTML
Design #3:
Aspects, Factors, Abstractions

95. Layer 7 Confidential 94
ALPS for HTML
ALPS profile URI
First designs in early 2011 (not registered)
“The purpose of Application-Level Profile Semantics (ALPS)
is to document the application-level semantics of a particular
implementation.”
“The example profile here contains details
on customizing the XHTML media type
for a specific application domain:
Micro-blogging.”

96. Layer 7 Confidential 95
ALPS for HTML
ALPS profile URI
Multiple parties building their own client or server
applications without seeing each other's work or accessing a
running "reference" implementation.
Developers are expected to rely on the constraints and
definitions found in this document (and the referenced
RFCs) as the sole instruction.

97. Layer 7 Confidential 96
ALPS for HTML
Messages

98. Layer 7 Confidential 97
ALPS for HTML
Messages

99. Layer 7 Confidential 98
ALPS for HTML
Messages

100. Layer 7 Confidential 99
ALPS for HTML
Server Code

101. Layer 7 Confidential 100
ALPS for HTML
Client Code

102. Layer 7 Confidential 101
ALPS for HTML
Client App

103. Layer 7 Confidential 102
ALPS for HTML
Client Bot

104. Layer 7 Confidential 103
ALPS for HTML
Client Bot

105. Layer 7 Confidential 104
ALPS for HTML
Client Bot

106. Layer 7 Confidential 105
ALPS for HTML
“In the wild…”

107. Layer 7 Confidential 106
ALPS for HTML
Rstat.us – Carol Nichols
“There are two things that make rstat.us special: simplicity
and openness.”
“[S]ince we already have a full-functioning end-user facing
site, the ALPS microblogging spec means adding a few
attributes rather than having to maintain a totally separate
API interface.”
“The current way of
presenting the ALPS
spec is [too] flat.”

108. Layer 7 Confidential 107
ALPS for HTML
Rstat.us – Carol Nichols

109. Layer 7 Confidential 108
ALPS for HTML
Rstat.us – Carol Nichols

110. Layer 7 Confidential 109
ALPS for HTML
Characteristics
- Domain Semantics Only
- Media-type agnostic
Benefits
- Focused on problem domain
- Treats “pages” as the “API”
Costs
- Very abstract model
- Tough to document
- Seems “over complex” esp. for M2M cases

111. Layer 7 Confidential 110
ALPS for HTML
“If HTML is not the only media-type
we need…”

112. Layer 7 Confidential 111
ALPS for HTML
“How do you choose?”

113. Layer 7 Confidential 112
Methodology
Mapping your domain to HTTP

114. Layer 7 Confidential 113
Designing messages is the primary work
Focus on mapping to payloads, not identifiers
Survey existing media types first
If you can’t find a suitable H-Factor signature
match, consider designing your own.
Pro Tip: you can always find a match.
Methodology

115. Layer 7 Confidential 114
Start with a format (XML, JSON, HTML, etc.)
You might need to support more than one
Don’t assume you can “cross-map” formats easily
Pro Tip: you almost always need to support more
than one.
Methodology

116. Layer 7 Confidential 115
Select your other design elements as needed
Methodology

117. Layer 7 Confidential 116
Represent State, not Objects
Remember both data and transitions
Craft lots of messages
Pro Tip: you can never have enough messages
Methodology

118. Layer 7 Confidential 117
When you are sure you have:
The proper format
The right H-Factor signature
The correct mapping of domain to messages
Sufficent message examples
Then, and only then…
Methodology

119. Layer 7 Confidential 118
You can start writing
the code
Methodology

120. Layer 7 Confidential 119
Because…
Methodology

121. Layer 7 Confidential 120
The code is only
the implementation
Methodology

122. Layer 7 Confidential 121
The code is only
the implementation
The media type is
the design.
Methodology

123. Layer 7 Confidential 122
And if you get the design
right...
Methodology

124. Layer 7 Confidential 123
Your users will be able
to do things
Methodology

125. Layer 7 Confidential 124
Your users will be able
to do things
Methodology

126. Layer 7 Confidential 125
Your users will be able
to do things
you never imagined
Methodology

127. Layer 7 Confidential 126
Mike Amundsen
The Costs and Benefits of
Building Hypermedia APIs
(with Node.js)
@mamund