The Costs and Benefits of Building Hypermedia APIs (with Node.js)

1,078 views

Published on

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.

Published in: Technology, News & Politics
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,078
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
0
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

The Costs and Benefits of Building Hypermedia APIs (with Node.js)

  1. 1. Layer 7 Confidential 1Mike AmundsenThe Costs and Benefits ofBuilding Hypermedia APIs(with Node.js)
  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/Building-Hypermedia-API
  3. 3. Presented at QCon San Franciscowww.qconsf.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. Layer 7 Confidential 2Mike AmundsenAuthorPresenterSoftware ExplorerPrincipal API Architect
  5. 5. Layer 7 Confidential 3OK, let’s get started…
  6. 6. Layer 7 Confidential 4Theonia"a looking at, viewing, beholding”
  7. 7. Layer 7 Confidential 5Theory"a looking at, viewing, beholding”
  8. 8. Layer 7 Confidential 6Praxis“doing”
  9. 9. Layer 7 Confidential 7Practice“doing”
  10. 10. Layer 7 Confidential 8First, a lesson to rememberfrom Donald Norman…
  11. 11. Layer 7 Confidential 10Affordances“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. 12. Layer 7 Confidential 11Affordances“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. 13. Layer 7 Confidential 12Affordances“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. 14. Layer 7 Confidential 13Affordances“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. 15. Layer 7 Confidential 14Affordances“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. 16. Layer 7 Confidential 15Some background…
  17. 17. Layer 7 Confidential 16AffordancesThe foundation for perception is ambient,ecologically available information.Affordances are all "action possibilities" latent inthe environment.Theory of Affordances, 1979- James J. Gibson
  18. 18. Layer 7 Confidential 17Seven Stages of ActionAffordancesThe Design of Everyday Things, 1988- Donald Norman
  19. 19. Layer 7 Confidential 18AffordancesKnowledge (“head” vs. “world”)April 17, 2012 APIs to Affordances : WS-REST 2012 18PropertyKnowledge in theWorldKnowledge in the HeadLearningLearning not required.Interpretationsubstitutes for learning.How easy it is tointerpret information isthe world dependsupon how well itexploits naturalmappings andconstraints.Requires learning, whichcan be considerable.Learning is made easier ifthere is meaning ofstructure to the material (orif there is a good mentalmodel).Efficiencyof useTends to be slowed upby the need to find andinterpret the externalinformation.Can be very efficientEase of useat firstencounterHigh Low
  20. 20. Layer 7 Confidential 19Affordances"Hypermedia is defined by the presence of applicationcontrol information embedded within, or as a layer above,the presentation of information“ (2001)“When I say [Hypermedia], I mean the simultaneouspresentation of information and controls such that theinformation becomes the affordance through which the userobtains choices and selects actions” (2008)Architectural Styles and the Designof Network-based Software, 2001- Roy T. Fielding
  21. 21. Layer 7 Confidential 20Affordances"Hypermedia is defined by the presence of applicationcontrol information embedded within, or as a layer above,the presentation of information“ (2001)“When I say [Hypermedia], I mean the simultaneouspresentation of information and controls such that theinformation becomes the affordance through which the userobtains choices and selects actions” (2008)Architectural Styles and the Designof Network-based Software, 2001- Roy T. Fielding
  22. 22. Layer 7 Confidential 21AffordancesAffordancesmakeHypermediapossible.
  23. 23. Layer 7 Confidential 22AffordancesHypermediacan provide aRich Set of Affordances
  24. 24. Layer 7 Confidential 23Maze+XMLDesign #1:A big pile of Affordances
  25. 25. Layer 7 Confidential 24Maze+XMLMaze+XML media typeFirst design in late 2010, registered w/ IANA 2011“…an XML data format for sharing maze state informationbetween clients and servers. It can be used to implementsimple mazes, adventure games, and other related data.”Read-only navigational linksNine link identifiers:collection, maze, start, exit, current,north, south, east, west
  26. 26. Layer 7 Confidential 25Maze+XMLMessage
  27. 27. Layer 7 Confidential 26Maze+XMLServer
  28. 28. Layer 7 Confidential 27Maze+XMLClient
  29. 29. Layer 7 Confidential 28Maze+XMLClient
  30. 30. Layer 7 Confidential 29Maze+XMLClient
  31. 31. Layer 7 Confidential 30Maze+XMLClient Code
  32. 32. Layer 7 Confidential 31Maze+XMLIn the wild…
  33. 33. Layer 7 Confidential 32Maze+XMLDarrel Miller“A good example of using link relations to conveydomain specific semantics.”“Has been a good test bed for trying to develop a UItransparently that tracks the state of the user agent as itnavigates between representations.”
  34. 34. Layer 7 Confidential 33Maze+XMLDarrel Miller – C#
  35. 35. Layer 7 Confidential 34Yannick Loiseau“I can say that a non-restful architecture would have been alot harder to deal with in bash, because hypermediaobviously made the maze exploration really easy”“I think that Link headers would be eveneasier to deal with…”Maze+XML
  36. 36. Layer 7 Confidential 35Yannick Loiseau - PythonMaze+XML
  37. 37. Layer 7 Confidential 36Yannick Loiseau - BashMaze+XML
  38. 38. Layer 7 Confidential 37Maze+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. 39. Layer 7 Confidential 38H-Factors“Pardon me, did you say ‘links’?”
  40. 40. Layer 7 Confidential 39“The H Factor of a media-type is a measure of thelevel of hypermedia support within that media-type.”“H Factor values can be used to compare andcontrast media types in order to aid in selecting theproper media-type(s) for yourimplementation.”H-FactorsREST: From Research to Practice :Hypermedia Types, 2011- Mike Amundsen
  41. 41. Layer 7 Confidential 40H-FactorsAnalyzing Media Types
  42. 42. Layer 7 Confidential 41H-FactorsAnalyzing Media Types
  43. 43. Layer 7 Confidential 42H-FactorsAnalyzing Media Types
  44. 44. Layer 7 Confidential 43H-FactorsThere are five LINK Factors(LO, LE, LT, LI, LN)There are four CONTROL Factors(CR, CU, CM, CL)
  45. 45. Layer 7 Confidential 44H-FactorsThere are five LINK Factors(LO, LE, LT, LI, LN)There are four CONTROL Factors(CR, CU, CM, CL)
  46. 46. Layer 7 Confidential 45H-FactorsLinkingOutbound Links (LO)
  47. 47. Layer 7 Confidential 46H-FactorsLinkingOutbound Links (LO)Embedded Links (LE)
  48. 48. Layer 7 Confidential 47H-FactorsLinkingOutbound Links (LO)Embedded Links (LE)Templated Links (LT)
  49. 49. Layer 7 Confidential 48H-FactorsLinkingOutbound Links (LO)Embedded Links (LE)Templated Links (LT)Idempotent Links (LI)
  50. 50. Layer 7 Confidential 49H-FactorsLinkingOutbound Links (LO)Embedded Links (LE)Templated Links (LT)Idempotent Links (LI)Non-Idempotent Links (LN)
  51. 51. Layer 7 Confidential 50H-FactorsThere are five LINK Factors(LO, LE, LT, LI, LN)There are four CONTROL Factors(CR, CU, CM, CL)
  52. 52. Layer 7 Confidential 51H-FactorsControlRequest Controls (CR)
  53. 53. Layer 7 Confidential 52H-FactorsControlRequest Controls (CR)Update Controls (CU)
  54. 54. Layer 7 Confidential 53H-FactorsControlRequest Controls (CR)Update Controls (CU)Method Controls (CM)
  55. 55. Layer 7 Confidential 54H-FactorsControlRequest Controls (CR)Update Controls (CU)Method Controls (CM)Link Controls (CL)
  56. 56. Layer 7 Confidential 55H-FactorsA pre-defined collection of H-Factors is called a“Media Type”Each media type has it’s own “H-Factor” signature.
  57. 57. Layer 7 Confidential 56H-FactorsH-Factors documentthe Affordancesof theMedia Type
  58. 58. Layer 7 Confidential 57H-Factors“OK, media types, affordances, I see…
  59. 59. Layer 7 Confidential 58Collection+JSONDesign #2:A read/write hypermedia type
  60. 60. Layer 7 Confidential 59Collection+JSONCollection+JSON media typeFirst designs in early 2011, registered w/ IANA mid 2011“…a JSON-based read/write hypermedia-type designed tosupport management and querying of simple collections.”It’s Atom w/ LT + templated writesVery limited link identifiers- collection, item, templates, query
  61. 61. Layer 7 Confidential 60MessageCollection+JSON
  62. 62. Layer 7 Confidential 61MessageCollection+JSON
  63. 63. Layer 7 Confidential 62MessageCollection+JSON
  64. 64. Layer 7 Confidential 63MessageCollection+JSON
  65. 65. Layer 7 Confidential 64MessageCollection+JSON
  66. 66. Layer 7 Confidential 65ServerCollection+JSON
  67. 67. Layer 7 Confidential 66ServerCollection+JSON
  68. 68. Layer 7 Confidential 67ServerCollection+JSON
  69. 69. Layer 7 Confidential 68Client CodeCollection+JSON
  70. 70. Layer 7 Confidential 69Client CodeCollection+JSON
  71. 71. Layer 7 Confidential 70Client CodeCollection+JSON
  72. 72. Layer 7 Confidential 71Client AppCollection+JSON
  73. 73. Layer 7 Confidential 72Client AppCollection+JSON
  74. 74. Layer 7 Confidential 73Collection+JSONIn the wild…
  75. 75. Layer 7 Confidential 74Collection+JSONNokia Research - Live Mixed Reality - Vlad Stribu“[Collection+JSON] … allows us to develop authoring toolsthat have the ability to self-adapt the user interface to theusage context.”
  76. 76. Layer 7 Confidential 75Collection+JSONNokia Research - Live Mixed Reality - Vlad Stribu“Collection+JSON was close enough to what we werelooking for…”“Most important factor that influenced our decision was thecommunity around this format…”
  77. 77. Layer 7 Confidential 76Collection+JSONCloudApp – Larry Marburger“CloudApp allows you to share images, links, music, videosand files.”“[Due to developer team changes] we had some setbackswith the Mac app and subsequently the API. We just startedworking with another developer whos making amazingprogress.”
  78. 78. Layer 7 Confidential 77Collection+JSONember.js – Yehuda Katz“A framework for creating ambitious applications.”“By default, its somewhat repetitive, but that can beaddressed…”“It was straight-forward to extend it with features I needed”“I am starting to feel like with the number of extensions, Ishould consider [creating] my own media type.”
  79. 79. Layer 7 Confidential 78Collection+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. 80. Layer 7 Confidential 79Affordance Aspects“So, are all affordances essentiallythe same?”
  81. 81. Layer 7 Confidential 80Affordance Aspects“For the purposes of applying affordances tohypermedia, there are four important aspectsto consider”
  82. 82. Layer 7 Confidential 81Affordance AspectsSafeThe HTTP protocol supports a number of "safe"actions such as HEAD, and GET.
  83. 83. Layer 7 Confidential 82Affordance AspectsSafeThe HTTP protocol supports a number of "safe"actions such as HEAD, and GET.The HTTP methods PUT, POST, and DELETE arecategorized as "unsafe" actions.
  84. 84. Layer 7 Confidential 83Affordance AspectsIdempotentWhen an HTML:FORM element has the METHODproperty set to "get" it represents an idempotentaction.
  85. 85. Layer 7 Confidential 84Affordance AspectsIdempotentWhen an HTML:FORM element has the METHODproperty set to "get" it represents an idempotentaction.When the same property is set to "post" theaffordance represents a non-idempotent action.
  86. 86. Layer 7 Confidential 85Affordance AspectsMutabilityHTML:FORM affords mutability
  87. 87. Layer 7 Confidential 86Affordance AspectsMutabilityHTML:FORM affords mutabilityHTML:LINK is immutable
  88. 88. Layer 7 Confidential 87Affordance AspectsTransclusionHTML:IMG affords transclusion
  89. 89. Layer 7 Confidential 88Affordance AspectsTransclusionHTML:IMG affords transclusionHTML:A does not
  90. 90. Layer 7 Confidential 89Affordance AspectsHowever, this single affordance is notvery usable.
  91. 91. Layer 7 Confidential 90Affordance AspectsMedia typesshould beusable
  92. 92. Layer 7 Confidential 91Affordance AspectsMessagesshould beusable
  93. 93. Layer 7 Confidential 92Affordance AspectsAPIsshould beusable
  94. 94. Layer 7 Confidential 93ALPS for HTMLDesign #3:Aspects, Factors, Abstractions
  95. 95. Layer 7 Confidential 94ALPS 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 particularimplementation.”“The example profile here contains detailson customizing the XHTML media typefor a specific application domain:Micro-blogging.”
  96. 96. Layer 7 Confidential 95ALPS for HTMLALPS profile URIMultiple parties building their own client or serverapplications without seeing each others work or accessing arunning "reference" implementation.Developers are expected to rely on the constraints anddefinitions found in this document (and the referencedRFCs) as the sole instruction.
  97. 97. Layer 7 Confidential 96ALPS for HTMLMessages
  98. 98. Layer 7 Confidential 97ALPS for HTMLMessages
  99. 99. Layer 7 Confidential 98ALPS for HTMLMessages
  100. 100. Layer 7 Confidential 99ALPS for HTMLServer Code
  101. 101. Layer 7 Confidential 100ALPS for HTMLClient Code
  102. 102. Layer 7 Confidential 101ALPS for HTMLClient App
  103. 103. Layer 7 Confidential 102ALPS for HTMLClient Bot
  104. 104. Layer 7 Confidential 103ALPS for HTMLClient Bot
  105. 105. Layer 7 Confidential 104ALPS for HTMLClient Bot
  106. 106. Layer 7 Confidential 105ALPS for HTML“In the wild…”
  107. 107. Layer 7 Confidential 106ALPS for HTMLRstat.us – Carol Nichols“There are two things that make rstat.us special: simplicityand openness.”“[S]ince we already have a full-functioning end-user facingsite, the ALPS microblogging spec means adding a fewattributes rather than having to maintain a totally separateAPI interface.”“The current way ofpresenting the ALPSspec is [too] flat.”
  108. 108. Layer 7 Confidential 107ALPS for HTMLRstat.us – Carol Nichols
  109. 109. Layer 7 Confidential 108ALPS for HTMLRstat.us – Carol Nichols
  110. 110. Layer 7 Confidential 109ALPS 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. 111. Layer 7 Confidential 110ALPS for HTML“If HTML is not the only media-typewe need…”
  112. 112. Layer 7 Confidential 111ALPS for HTML“How do you choose?”
  113. 113. Layer 7 Confidential 112MethodologyMapping your domain to HTTP
  114. 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 signaturematch, consider designing your own.Pro Tip: you can always find a match.Methodology
  115. 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 morethan one.Methodology
  116. 116. Layer 7 Confidential 115Select your other design elements as neededMethodology
  117. 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 messagesMethodology
  118. 118. Layer 7 Confidential 117When you are sure you have:The proper formatThe right H-Factor signatureThe correct mapping of domain to messagesSufficent message examplesThen, and only then…Methodology
  119. 119. Layer 7 Confidential 118You can start writingthe codeMethodology
  120. 120. Layer 7 Confidential 119Because…Methodology
  121. 121. Layer 7 Confidential 120The code is onlythe implementationMethodology
  122. 122. Layer 7 Confidential 121The code is onlythe implementationThe media type isthe design.Methodology
  123. 123. Layer 7 Confidential 122And if you get the designright...Methodology
  124. 124. Layer 7 Confidential 123Your users will be ableto do thingsMethodology
  125. 125. Layer 7 Confidential 124Your users will be ableto do thingsMethodology
  126. 126. Layer 7 Confidential 125Your users will be ableto do thingsyou never imaginedMethodology
  127. 127. Layer 7 Confidential 126Mike AmundsenThe Costs and Benefits ofBuilding Hypermedia APIs(with Node.js)@mamund

×