RESTing in the ALPSGeneric Hypermedia and Domain-SpecificAPIs@mamundMike AmundsenPrincipal API Architect,Layer 7 Technolog...
InfoQ.com: News & Community Site• 750,000 unique visitors/month• Published in 4 languages (English, Chinese, Japanese and ...
Presented at QCon Londonwww.qconlondon.comPurpose of QCon- to empower software development by facilitating the spread ofkn...
A simple storyIn three parts...
The bona fidesHow we got here...
The confessionI left some stuff out...
Where I make amendsThe payoff
Ok, lets begin...
How we got here...The bona fides
Lets start with a quote from 2002
Fielding and Taylor, 2002"REST provides [this] byfocusing on a shared understandingof data types with metadata..."
That phrase struck me.
It has become a prime motivator for me.
focusing
focusingon
focusingonshared understanding
shared understanding
How do we share understandingon the Web?
protocols
protocolshttpftpsmtpdnswsxmpp
But thats not all...
Fielding & Taylor, 2002"REST components communicate bytransferring a representation of the datain a format matching one of...
standard data typeshtmlcsvhalatomjsonCj
registered media typeshtmlcsvhalatomjsonCj
messageshtmlcsvhalatomjsonCj
We share understanding via messages.
Description
Discovery
Hypermedia
These messages tell us whatprotocol actions are possible.
These messages tell us whatprotocol actions are possible.
How is this done in a message?
affordances
hypermediaaffordances
protocolhypermediaaffordances
Back in 2010, I called those...
H-Factors
H-Factors
H-FactorsIdentify nine features forsharing understandingabout protocol actions.
H-Factors
H-Factors
H-Factors
H-FactorsIdentify the affordances
H-Factors
H-FactorsCategorize them.
H-Factors
H-FactorsFor lots of media type designs.
H-Factors
H-Factors
H-Factors
H-Factors
H-FactorsThis gives us a tool for lots of tasks...
H-FactorsWe can analyze existing designs
H-FactorsWe can categorize types forbest fit implementations
H-FactorsWe can use H-Factors tomodel prototype designs
H-Factors
H-FactorsWe now have ashared understandingabout protocol affordances
H-Factors
H-Factors
H-FactorsAnd this is all good.
H-FactorsBut...
H-FactorsTheres a problem here.
H-FactorsAn important piece is missing.
H-FactorsThere is a "gap"between theory and practice
H-FactorsThere is a "gap"between H-Factors and "the real world"
I ignored this "gap" when identifying H-Factors.
I side-stepped the "gap" in the last book.
H-Factors
And this "gap" is a key theme in the next book.
H-FactorsYep, you might say...
I left some stuff out.The confession
The confessionI ignored the "hard" parts ...
The confession
The confessionWhat are those?
The confession
The confessionTheyre rather specific.
The confession
The confessionaffordances?
The confession
The confessionWell, they are notprotocol affordances
The confessionI call themapplication affordances
The confessionBut there is another name for these...
VocabulariesSrsly?
VocabulariesOn the Web,representations containprotocol AND applicationaffordances
VocabulariesWe share understandingat the application-level, too.
VocabulariesWell, "we" means us humans.
VocabulariesDo we share app-level understanding?
VocabulariesHow about now?
VocabulariesHow about now?
VocabulariesHuman app-level affordances
VocabulariesMachine app-level affordances
VocabulariesOf course, weve known thisfor quite a while.
VocabulariesThere has been quite a bit of workon vocabulariesdublin coremicroformatsactivity streamsschema.orgVoID
VocabulariesVocabularies can provideshared understandingof theapplication-specific affordances
VocabulariesAnd this is all good.
VocabulariesBut...
VocabulariesTheres a problem here.
VocabulariesAn important piece is missing.
VocabulariesThere is a "gap"between theory and practice
VocabulariesThere is a "gap"between Vocabularies and "the real world"
VocabulariesVocabularies only modelthe "what"state
VocabulariesVocabularies only modelthe "what"not the "how"statetransitions
VocabulariesI know what a Person is, but how can I interact with it?
VocabulariesI know what an hProduct is, but how can I interact with it?
VocabulariesI know what an ActivityStream is, but how can I interact with it?
The payoffWhere I make amends
The payoffWhat if we combinedthe "what" of vocabulariesstate
The payoffWhat if we combinedthe "what" of vocabularieswiththe "how" of protocols?statetransitions
The payoffWhat would that look like?statetransitions
The payoffXHTML Meta Data Profiles (XMDP)Tantek Celik, 2003
The payoffA few years on, a similar approach...
The payoffALPS - Microblogging with XHTMLMike Amundsen, 2011
The payoffALPS includes both state and transitions
The payoffALPS(mb) hackathonat 2011 RESTFest.Initial experiment was a success.Independently built apps could interop.
The payoffMicroblogging site rstatusimplements ALPS(mb) in 2012
The payoffALPS(mb) was a good ideabut we can do better.
The payoffHow about a profile specthat includes bothstate and transitionsthat works fora wide rangeof media types?
Application-Level ProfileSemanticsThe sequel
ALPSWarning!What follows is early-stage,tentative design
ALPSDesign and register two media types fordescribing problem domains.application/alps+xml (or +json)
ALPS
ALPS
ALPS
ALPS
ALPSFour possible descriptor types:1. semantic (data)2. safe (HTTP.GET)3. unsafe (HTTP.POST)4. idempotent (HTTP.PUT & HTTP...
ALPS
ALPSALPS id properties become representationidentifiers● @class, @rel, @name (HTML)● @rel, @name (Cj, HAL)● @rel (Atom)
ALPSApply these semantics to a wide range ofexisting media types
ALPS
ALPSThere will be a set of rules forapplying ALPS semanticsto each media type.
ALPS
ALPSBy applying semantic descriptorsconsistently...
ALPS
ALPSselectingan implementation media typecan be independent of thestate and transitionsemantics.
ALPS
ALPSselecting a reference vocabularycan be independent of theprotocol semantics
ALPS
ALPSALPS spec will provide several markup elements
ALPSNow we have a wayto share understanding
ALPSNow we have a wayto share understandingabout a problem domain
ALPSNow we have a wayto share understandingabout a problem domainNot a service document (WSDL)
ALPSNow we have a wayto share understandingabout a problem domainNot a discovery document (Google, @mnot)
ALPSNow we have a wayto share understandingabout a problem domainNot a hypermedia type (HAL, Cj, Siren, etc.)
ALPSNow we have a wayto share understandingabout a problem domainNot a vocabulary repository
ALPSNow we have a wayto share understandingabout a problem domainNot an object graph
ALPSThis could give us tools for lots of tasks...
ALPSDescribing a domain profile
ALPSAnalyzing domain profiles
ALPSMatching domain profiles to media types
ALPSSharing selected state with multiple servicesschema.org/Persongift listscontactsphotosancestry treematchmakerschool pals
ALPSDocumenting domain profiles
ALPSDriving server-side representation engines
ALPSDriving client-side processing engines
ALPSPossible benefits of ALPS Repositories:● Share your domain profiles● Search for profiles by topic● Match abstracts w/ ...
So, where are we headed now?Summary
Snowflakes still commonprogrammableWeb, 2012Summary
How many data types here?programmableWeb, 2012Summary
How much shared understanding here?programmableWeb, 2012Summary
Fielding & Taylor, 2002"REST components communicate bytransferring a representation of the datain a format matching one of...
standard data typesincludes bothstate and transition typesSummary
shared understandingincludes bothstate and transition typesSummary
because the Webincludes bothstate and transition typesSummary
protocolshttpftpsmtpdnswsxmpp
media typeshtmlcsvhalatomjsonCj
dublin coremicroformatsactivity streamsschema.orgVoIDvocabularies
micro-blogginghProductPersonvCardaccountingdomain profiles
Summary● ALPS IETF I-D will be posted in March● Watch my blog/twitter for details● Looking for feedback/contributions
RESTing in the ALPSGeneric Hypermedia and Domain-SpecificAPIs@mamundMike AmundsenPrincipal API Architect,Layer 7 Technolog...
Upcoming SlideShare
Loading in …5
×

Generic Hypermedia and Domain-Specific APIs: RESTing in the ALPS

582 views

Published on

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.

Published in: Technology

Generic Hypermedia and Domain-Specific APIs: RESTing in the ALPS

  1. 1. RESTing in the ALPSGeneric Hypermedia and Domain-SpecificAPIs@mamundMike AmundsenPrincipal API Architect,Layer 7 Technologies
  2. 2. InfoQ.com: News & Community Site• 750,000 unique visitors/month• Published in 4 languages (English, Chinese, Japanese and BrazilianPortuguese)• 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 / monthWatch the video with slidesynchronization on InfoQ.com!http://www.infoq.com/presentations/web-api-alps
  3. 3. Presented at QCon Londonwww.qconlondon.comPurpose of QCon- to empower software development by facilitating the spread ofknowledge and innovationStrategy- practitioner-driven conference designed for YOU: influencers ofchange and innovation in your teams- speakers and topics driving the evolution and innovation- connecting and catalyzing the influencers and innovatorsHighlights- attended by more than 12,000 delegates since 2007- held in 9 cities worldwide
  4. 4. A simple storyIn three parts...
  5. 5. The bona fidesHow we got here...
  6. 6. The confessionI left some stuff out...
  7. 7. Where I make amendsThe payoff
  8. 8. Ok, lets begin...
  9. 9. How we got here...The bona fides
  10. 10. Lets start with a quote from 2002
  11. 11. Fielding and Taylor, 2002"REST provides [this] byfocusing on a shared understandingof data types with metadata..."
  12. 12. That phrase struck me.
  13. 13. It has become a prime motivator for me.
  14. 14. focusing
  15. 15. focusingon
  16. 16. focusingonshared understanding
  17. 17. shared understanding
  18. 18. How do we share understandingon the Web?
  19. 19. protocols
  20. 20. protocolshttpftpsmtpdnswsxmpp
  21. 21. But thats not all...
  22. 22. Fielding & Taylor, 2002"REST components communicate bytransferring a representation of the datain a format matching one ofan evolving set of standard data types..."
  23. 23. standard data typeshtmlcsvhalatomjsonCj
  24. 24. registered media typeshtmlcsvhalatomjsonCj
  25. 25. messageshtmlcsvhalatomjsonCj
  26. 26. We share understanding via messages.
  27. 27. Description
  28. 28. Discovery
  29. 29. Hypermedia
  30. 30. These messages tell us whatprotocol actions are possible.
  31. 31. These messages tell us whatprotocol actions are possible.
  32. 32. How is this done in a message?
  33. 33. affordances
  34. 34. hypermediaaffordances
  35. 35. protocolhypermediaaffordances
  36. 36. Back in 2010, I called those...
  37. 37. H-Factors
  38. 38. H-Factors
  39. 39. H-FactorsIdentify nine features forsharing understandingabout protocol actions.
  40. 40. H-Factors
  41. 41. H-Factors
  42. 42. H-Factors
  43. 43. H-FactorsIdentify the affordances
  44. 44. H-Factors
  45. 45. H-FactorsCategorize them.
  46. 46. H-Factors
  47. 47. H-FactorsFor lots of media type designs.
  48. 48. H-Factors
  49. 49. H-Factors
  50. 50. H-Factors
  51. 51. H-Factors
  52. 52. H-FactorsThis gives us a tool for lots of tasks...
  53. 53. H-FactorsWe can analyze existing designs
  54. 54. H-FactorsWe can categorize types forbest fit implementations
  55. 55. H-FactorsWe can use H-Factors tomodel prototype designs
  56. 56. H-Factors
  57. 57. H-FactorsWe now have ashared understandingabout protocol affordances
  58. 58. H-Factors
  59. 59. H-Factors
  60. 60. H-FactorsAnd this is all good.
  61. 61. H-FactorsBut...
  62. 62. H-FactorsTheres a problem here.
  63. 63. H-FactorsAn important piece is missing.
  64. 64. H-FactorsThere is a "gap"between theory and practice
  65. 65. H-FactorsThere is a "gap"between H-Factors and "the real world"
  66. 66. I ignored this "gap" when identifying H-Factors.
  67. 67. I side-stepped the "gap" in the last book.
  68. 68. H-Factors
  69. 69. And this "gap" is a key theme in the next book.
  70. 70. H-FactorsYep, you might say...
  71. 71. I left some stuff out.The confession
  72. 72. The confessionI ignored the "hard" parts ...
  73. 73. The confession
  74. 74. The confessionWhat are those?
  75. 75. The confession
  76. 76. The confessionTheyre rather specific.
  77. 77. The confession
  78. 78. The confessionaffordances?
  79. 79. The confession
  80. 80. The confessionWell, they are notprotocol affordances
  81. 81. The confessionI call themapplication affordances
  82. 82. The confessionBut there is another name for these...
  83. 83. VocabulariesSrsly?
  84. 84. VocabulariesOn the Web,representations containprotocol AND applicationaffordances
  85. 85. VocabulariesWe share understandingat the application-level, too.
  86. 86. VocabulariesWell, "we" means us humans.
  87. 87. VocabulariesDo we share app-level understanding?
  88. 88. VocabulariesHow about now?
  89. 89. VocabulariesHow about now?
  90. 90. VocabulariesHuman app-level affordances
  91. 91. VocabulariesMachine app-level affordances
  92. 92. VocabulariesOf course, weve known thisfor quite a while.
  93. 93. VocabulariesThere has been quite a bit of workon vocabulariesdublin coremicroformatsactivity streamsschema.orgVoID
  94. 94. VocabulariesVocabularies can provideshared understandingof theapplication-specific affordances
  95. 95. VocabulariesAnd this is all good.
  96. 96. VocabulariesBut...
  97. 97. VocabulariesTheres a problem here.
  98. 98. VocabulariesAn important piece is missing.
  99. 99. VocabulariesThere is a "gap"between theory and practice
  100. 100. VocabulariesThere is a "gap"between Vocabularies and "the real world"
  101. 101. VocabulariesVocabularies only modelthe "what"state
  102. 102. VocabulariesVocabularies only modelthe "what"not the "how"statetransitions
  103. 103. VocabulariesI know what a Person is, but how can I interact with it?
  104. 104. VocabulariesI know what an hProduct is, but how can I interact with it?
  105. 105. VocabulariesI know what an ActivityStream is, but how can I interact with it?
  106. 106. The payoffWhere I make amends
  107. 107. The payoffWhat if we combinedthe "what" of vocabulariesstate
  108. 108. The payoffWhat if we combinedthe "what" of vocabularieswiththe "how" of protocols?statetransitions
  109. 109. The payoffWhat would that look like?statetransitions
  110. 110. The payoffXHTML Meta Data Profiles (XMDP)Tantek Celik, 2003
  111. 111. The payoffA few years on, a similar approach...
  112. 112. The payoffALPS - Microblogging with XHTMLMike Amundsen, 2011
  113. 113. The payoffALPS includes both state and transitions
  114. 114. The payoffALPS(mb) hackathonat 2011 RESTFest.Initial experiment was a success.Independently built apps could interop.
  115. 115. The payoffMicroblogging site rstatusimplements ALPS(mb) in 2012
  116. 116. The payoffALPS(mb) was a good ideabut we can do better.
  117. 117. The payoffHow about a profile specthat includes bothstate and transitionsthat works fora wide rangeof media types?
  118. 118. Application-Level ProfileSemanticsThe sequel
  119. 119. ALPSWarning!What follows is early-stage,tentative design
  120. 120. ALPSDesign and register two media types fordescribing problem domains.application/alps+xml (or +json)
  121. 121. ALPS
  122. 122. ALPS
  123. 123. ALPS
  124. 124. ALPS
  125. 125. ALPSFour possible descriptor types:1. semantic (data)2. safe (HTTP.GET)3. unsafe (HTTP.POST)4. idempotent (HTTP.PUT & HTTP.DELETE)
  126. 126. ALPS
  127. 127. ALPSALPS id properties become representationidentifiers● @class, @rel, @name (HTML)● @rel, @name (Cj, HAL)● @rel (Atom)
  128. 128. ALPSApply these semantics to a wide range ofexisting media types
  129. 129. ALPS
  130. 130. ALPSThere will be a set of rules forapplying ALPS semanticsto each media type.
  131. 131. ALPS
  132. 132. ALPSBy applying semantic descriptorsconsistently...
  133. 133. ALPS
  134. 134. ALPSselectingan implementation media typecan be independent of thestate and transitionsemantics.
  135. 135. ALPS
  136. 136. ALPSselecting a reference vocabularycan be independent of theprotocol semantics
  137. 137. ALPS
  138. 138. ALPSALPS spec will provide several markup elements
  139. 139. ALPSNow we have a wayto share understanding
  140. 140. ALPSNow we have a wayto share understandingabout a problem domain
  141. 141. ALPSNow we have a wayto share understandingabout a problem domainNot a service document (WSDL)
  142. 142. ALPSNow we have a wayto share understandingabout a problem domainNot a discovery document (Google, @mnot)
  143. 143. ALPSNow we have a wayto share understandingabout a problem domainNot a hypermedia type (HAL, Cj, Siren, etc.)
  144. 144. ALPSNow we have a wayto share understandingabout a problem domainNot a vocabulary repository
  145. 145. ALPSNow we have a wayto share understandingabout a problem domainNot an object graph
  146. 146. ALPSThis could give us tools for lots of tasks...
  147. 147. ALPSDescribing a domain profile
  148. 148. ALPSAnalyzing domain profiles
  149. 149. ALPSMatching domain profiles to media types
  150. 150. ALPSSharing selected state with multiple servicesschema.org/Persongift listscontactsphotosancestry treematchmakerschool pals
  151. 151. ALPSDocumenting domain profiles
  152. 152. ALPSDriving server-side representation engines
  153. 153. ALPSDriving client-side processing engines
  154. 154. ALPSPossible 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. 155. So, where are we headed now?Summary
  156. 156. Snowflakes still commonprogrammableWeb, 2012Summary
  157. 157. How many data types here?programmableWeb, 2012Summary
  158. 158. How much shared understanding here?programmableWeb, 2012Summary
  159. 159. Fielding & Taylor, 2002"REST components communicate bytransferring a representation of the datain a format matching one ofan evolving set of standard data types..."
  160. 160. standard data typesincludes bothstate and transition typesSummary
  161. 161. shared understandingincludes bothstate and transition typesSummary
  162. 162. because the Webincludes bothstate and transition typesSummary
  163. 163. protocolshttpftpsmtpdnswsxmpp
  164. 164. media typeshtmlcsvhalatomjsonCj
  165. 165. dublin coremicroformatsactivity streamsschema.orgVoIDvocabularies
  166. 166. micro-blogginghProductPersonvCardaccountingdomain profiles
  167. 167. Summary● ALPS IETF I-D will be posted in March● Watch my blog/twitter for details● Looking for feedback/contributions
  168. 168. RESTing in the ALPSGeneric Hypermedia and Domain-SpecificAPIs@mamundMike AmundsenPrincipal API Architect,Layer 7 TechnologiesLets talk!

×