The document discusses the author's realization that his previous work on H-Factors for describing protocol affordances was missing a consideration of "application affordances". This led to the idea of "vocabularies" for describing shared understanding at the application level. However, vocabularies alone do not describe how to interact with application concepts. The author proposes a new specification called ALPS that combines the description of application concepts ("what") using vocabularies, along with the description of how to interact with those concepts using hypermedia controls and protocols ("how"). ALPS aims to provide shared understanding of both the state and transitions of application domains across different media types and implementations.

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

2. A simple story
In three parts...

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

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

5. Where I make amends
The payoff

6. Ok, let's begin...

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

8. Let's start with a quote from 2002

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

10. That phrase struck me.

11. It has become a prime motivator for me.

12. focusing

13. focusing
on

14. focusing
on
shared understanding

15. shared understanding

16. How do we share understanding
on the Web?

17. protocols

18. http
ftp
smtp
protocols
dns
ws
xmpp

19. But that's not all...

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

21. html
csv
hal
standard data types
atom
json
Cj

22. html
csv
hal
registered media types
atom
json
Cj

23. html
csv
hal
messages
atom
json
Cj

24. We share understanding via messages.

25. Description

26. Discovery

27. Hypermedia

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

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

30. How is this done in a message?

31. affordances

32. hypermedia
affordances

33. protocol
hypermedia
affordances

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

35. H-Factors

36. H-Factors

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

38. H-Factors

39. H-Factors

40. H-Factors

41. H-Factors
Identify the affordances

42. H-Factors

43. H-Factors
Categorize them.

44. H-Factors

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

46. H-Factors

47. H-Factors

48. H-Factors

49. H-Factors

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

51. H-Factors
We can analyze existing designs

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

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

54. H-Factors

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

56. H-Factors

57. H-Factors

58. H-Factors
And this is all good.

59. H-Factors
But...

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

61. H-Factors
An important piece is missing.

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

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

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

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

66. H-Factors

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

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

69. I left some stuff out.
The confession

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

71. The confession

72. The confession
What are those?

73. The confession

74. The confession
They're rather specific.

75. The confession

76. The confession
affordances?

77. The confession

78. The confession
Well, they are not
protocol affordances

79. The confession
I call them
application affordances

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

81. Vocabularies
Srsly?

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

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

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

85. Vocabularies
Do we share app-level understanding?

86. Vocabularies
How about now?

87. Vocabularies
How about now?

88. Vocabularies
Human app-level affordances

89. Vocabularies
Machine app-level affordances

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

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

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

93. Vocabularies
And this is all good.

94. Vocabularies
But...

95. Vocabularies
There's a problem here.

96. Vocabularies
An important piece is missing.

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

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

99. Vocabularies
state
Vocabularies only model
the "what"

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

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

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

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

104. The payoff
Where I make amends

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

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

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

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

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

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

111. The payoff
ALPS includes both state and transitions

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

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

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

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

116. Application-Level Profile
Semantics
The sequel

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

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

119. ALPS

120. ALPS

121. ALPS

122. ALPS

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

124. ALPS

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

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

127. ALPS

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

129. ALPS

130. ALPS
By applying semantic descriptors
consistently...

131. ALPS

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

133. ALPS

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

135. ALPS

136. ALPS
ALPS spec will provide several markup elements

137. ALPS
Now we have a way
to share understanding

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

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

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

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

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

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

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

145. ALPS
Describing a domain profile

146. ALPS
Analyzing domain profiles

147. ALPS
Matching domain profiles to media types

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

149. ALPS
Documenting domain profiles

150. ALPS
Driving server-side representation engines

151. ALPS
Driving client-side processing engines

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

153. Summary
So, where are we headed now?

154. Summary
Snowflakes still common
programmableWeb, 2012

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

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

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

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

159. Summary
shared understanding
includes both
state and transition types

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

161. http
ftp
smtp
protocols
dns
ws
xmpp

162. html
csv
hal
media types
atom
json
Cj

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

164. vCard
micro-blogging
domain profiles
Person
hProduct
accounting

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

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