Video and slides synchronized, mp3 and slide download available at http://bit.ly/ZbFXvL. This talk describes the ALPS standard; a way to define the data and workflow details for a Web application and apply these details consistently regardless of the media type in use. Working examples in the talk also show how this standardized definition can make designing, implementing, documenting, and maintaining Web APIs easier and more consistent across multiple media types. Filmed at qconlondon.com. As Principal API Architect for Layer 7 Technologies, Mike Amundsen’s job is to help people build great APIs for the Web. He has more than a dozen books to his credit. His most recent book is "Building Hypermedia APIs with HTML5 and Node" He also contributed to the book "RESTful Web Services Cookbook" (by Subbu Allamaraju) and is currently working on a new book on programming with the Cloud9 IDE.

1. RESTing in the ALPS
Generic Hypermedia and Domain-Specific
APIs
@mamund
Mike Amundsen
Principal API Architect,
Layer 7 Technologies

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
/web-api-alps

3. Presented at QCon London
www.qconlondon.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. A simple story
In three parts...

5. The bona fides
How we got here...

6. The confession
I left some stuff out...

7. Where I make amends
The payoff

8. Ok, let's begin...

9. How we got here...
The bona fides

10. Let's start with a quote from 2002

11. Fielding and Taylor, 2002
"REST provides [this] by
focusing on a shared understanding
of data types with metadata..."

12. That phrase struck me.

13. It has become a prime motivator for me.

14. focusing

15. focusing
on

16. focusing
on
shared understanding

17. shared understanding

18. How do we share understanding
on the Web?

19. protocols

20. protocols
http
ftp
smtp
dns
ws
xmpp

21. But that's not all...

22. Fielding & Taylor, 2002
"REST components communicate by
transferring a representation of the data
in a format matching one of
an evolving set of standard data types..."

23. standard data types
html
csv
hal
atom
json
Cj

24. registered media types
html
csv
hal
atom
json
Cj

25. messages
html
csv
hal
atom
json
Cj

26. We share understanding via messages.

27. Description

28. Discovery

29. Hypermedia

30. These messages tell us what
protocol actions are possible.

31. These messages tell us what
protocol actions are possible.

32. How is this done in a message?

33. affordances

34. hypermedia
affordances

35. protocol
hypermedia
affordances

36. Back in 2010, I called those...

37. H-Factors

38. H-Factors

39. H-Factors
Identify nine features for
sharing understanding
about protocol actions.

40. H-Factors

41. H-Factors

42. H-Factors

43. H-Factors
Identify the affordances

44. H-Factors

45. H-Factors
Categorize them.

46. H-Factors

47. H-Factors
For lots of media type designs.

48. H-Factors

49. H-Factors

50. H-Factors

51. H-Factors

52. H-Factors
This gives us a tool for lots of tasks...

53. H-Factors
We can analyze existing designs

54. H-Factors
We can categorize types for
'best fit' implementations

55. H-Factors
We can use H-Factors to
model prototype designs

56. H-Factors

57. H-Factors
We now have a
shared understanding
about protocol affordances

58. H-Factors

59. H-Factors

60. H-Factors
And this is all good.

61. H-Factors
But...

62. H-Factors
There's a problem here.

63. H-Factors
An important piece is missing.

64. H-Factors
There is a "gap"
between theory and practice

65. H-Factors
There is a "gap"
between H-Factors and "the real world"

66. I ignored this "gap" when identifying H-Factors.

67. I side-stepped the "gap" in the last book.

68. H-Factors

69. And this "gap" is a key theme in the next book.

70. H-Factors
Yep, you might say...

71. I left some stuff out.
The confession

72. The confession
I ignored the "hard" parts ...

73. The confession

74. The confession
What are those?

75. The confession

76. The confession
They're rather specific.

77. The confession

78. The confession
affordances?

79. The confession

80. The confession
Well, they are not
protocol affordances

81. The confession
I call them
application affordances

82. The confession
But there is another name for these...

83. Vocabularies
Srsly?

84. Vocabularies
On the Web,
representations contain
protocol AND application
affordances

85. Vocabularies
We share understanding
at the application-level, too.

86. Vocabularies
Well, "we" means us humans.

87. Vocabularies
Do we share app-level understanding?

88. Vocabularies
How about now?

89. Vocabularies
How about now?

90. Vocabularies
Human app-level affordances

91. Vocabularies
Machine app-level affordances

92. Vocabularies
Of course, we've known this
for quite a while.

93. Vocabularies
There has been quite a bit of work
on vocabularies
dublin core
microformats
activity streams
schema.org
VoID

94. Vocabularies
Vocabularies can provide
shared understanding
of the
application-specific affordances

95. Vocabularies
And this is all good.

96. Vocabularies
But...

97. Vocabularies
There's a problem here.

98. Vocabularies
An important piece is missing.

99. Vocabularies
There is a "gap"
between theory and practice

100. Vocabularies
There is a "gap"
between Vocabularies and "the real world"

101. Vocabularies
Vocabularies only model
the "what"
state

102. Vocabularies
Vocabularies only model
the "what"
not the "how"
state
transitions

103. Vocabularies
I know what a Person is, but how can I interact with it?

104. Vocabularies
I know what an hProduct is, but how can I interact with it?

105. Vocabularies
I know what an ActivityStream is, but how can I interact with it?

106. The payoff
Where I make amends

107. The payoff
What if we combined
the "what" of vocabularies
state

108. The payoff
What if we combined
the "what" of vocabularies
with
the "how" of protocols?
state
transitions

109. The payoff
What would that look like?
state
transitions

110. The payoff
XHTML Meta Data Profiles (XMDP)
Tantek Celik, 2003

111. The payoff
A few years on, a similar approach...

112. The payoff
ALPS - Microblogging with XHTML
Mike Amundsen, 2011

113. The payoff
ALPS includes both state and transitions

114. The payoff
ALPS(mb) hackathon
at 2011 RESTFest.
Initial experiment was a success.
Independently built apps could interop.

115. The payoff
Microblogging site rstatus
implements ALPS(mb) in 2012

116. The payoff
ALPS(mb) was a good idea
but we can do better.

117. The payoff
How about a profile spec
that includes both
state and transitions
that works for
a wide range
of media types?

118. Application-Level Profile
Semantics
The sequel

119. ALPS
Warning!
What follows is early-stage,
tentative design

120. ALPS
Design and register two media types for
describing problem domains.
application/alps+xml (or +json)

121. ALPS

122. ALPS

123. ALPS

124. ALPS

125. ALPS
Four possible descriptor types:
1. semantic (data)
2. safe (HTTP.GET)
3. unsafe (HTTP.POST)
4. idempotent (HTTP.PUT & HTTP.DELETE)

126. ALPS

127. ALPS
ALPS 'id' properties become representation
identifiers
● @class, @rel, @name (HTML)
● @rel, @name (Cj, HAL)
● @rel (Atom)

128. ALPS
Apply these semantics to a wide range of
existing media types

129. ALPS

130. ALPS
There will be a set of rules for
applying ALPS semantics
to each media type.

131. ALPS

132. ALPS
By applying semantic descriptors
consistently...

133. ALPS

134. ALPS
selecting
an implementation media type
can be independent of the
state and transition
semantics.

135. ALPS

136. ALPS
selecting a reference vocabulary
can be independent of the
protocol semantics

137. ALPS

138. ALPS
ALPS spec will provide several markup elements

139. ALPS
Now we have a way
to share understanding

140. ALPS
Now we have a way
to share understanding
about a problem domain

141. ALPS
Now we have a way
to share understanding
about a problem domain
Not a service document (WSDL)

142. ALPS
Now we have a way
to share understanding
about a problem domain
Not a discovery document (Google, @mnot)

143. ALPS
Now we have a way
to share understanding
about a problem domain
Not a hypermedia type (HAL, Cj, Siren, etc.)

144. ALPS
Now we have a way
to share understanding
about a problem domain
Not a vocabulary repository

145. ALPS
Now we have a way
to share understanding
about a problem domain
Not an object graph

146. ALPS
This could give us tools for lots of tasks...

147. ALPS
Describing a domain profile

148. ALPS
Analyzing domain profiles

149. ALPS
Matching domain profiles to media types

150. ALPS
Sharing selected state with multiple services
schema.org/Person
gift lists
contacts
photos
ancestry tree
matchmaker
school pals

151. ALPS
Documenting domain profiles

152. ALPS
Driving server-side representation engines

153. ALPS
Driving client-side processing engines

154. ALPS
Possible benefits of ALPS Repositories:
● Share your domain profiles
● Search for profiles by topic
● Match abstracts w/ favored vocabularies
● Reflect aggregate profile use/reference data

155. So, where are we headed now?
Summary

156. Snowflakes still common
programmableWeb, 2012
Summary

157. How many data types here?
programmableWeb, 2012
Summary

158. How much shared understanding here?
programmableWeb, 2012
Summary

159. Fielding & Taylor, 2002
"REST components communicate by
transferring a representation of the data
in a format matching one of
an evolving set of standard data types..."

160. standard data types
includes both
state and transition types
Summary

161. shared understanding
includes both
state and transition types
Summary

162. because the Web
includes both
state and transition types
Summary

163. protocols
http
ftp
smtp
dns
ws
xmpp

164. media types
html
csv
hal
atom
json
Cj

165. dublin core
microformats
activity streams
schema.org
VoID
vocabularies

166. micro-blogging
hProduct
Person
vCard
accounting
domain profiles

167. Summary
● ALPS IETF I-D will be posted in March
● Watch my blog/twitter for details
● Looking for feedback/contributions

168. RESTing in the ALPS
Generic Hypermedia and Domain-Specific
APIs
@mamund
Mike Amundsen
Principal API Architect,
Layer 7 Technologies
Let's talk!