Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Mike AmundsenThe Costs and Benefits ofBuilding Hypermedia APIs(with Node.js)                      Layer 7 Confidential   1
Mike AmundsenAuthorPresenterSoftware ExplorerPrincipal API Architect                           Layer 7 Confidential   2
OK, let‟s get started…                     Layer 7 Confidential   3
Theonia  "a looking at, viewing, beholding”                        Layer 7 Confidential   4
Theory "a looking at, viewing, beholding”                       Layer 7 Confidential   5
Praxis                   “doing”         Layer 7 Confidential   6
Practice                     “doing”           Layer 7 Confidential   7
First, a lesson to remember  from Donald Norman…                        Layer 7 Confidential   8
Affordances“The value of a well-designed object,Is when it has such a rich set of affordances,That the people who use it,C...
Affordances“The value of a well-designed object,Is when it has such a rich set of affordances,That the people who use it,C...
Affordances“The value of a well-designed object,Is when it has such a rich set of affordances,That the people who use it,C...
Affordances“The value of a well-designed object,Is when it has such a rich set of affordances,That the people who use it,C...
Affordances“The value of a well-designed object,Is when it has such a rich set of affordances,That the people who use it,C...
Some background…                   Layer 7 Confidential   15
AffordancesThe foundation for perception is ambient, ecologically available information.Affordances are all "action poss...
Affordances Seven Stages of ActionThe Design of Everyday Things, 1988- Donald Norman                                     ...
AffordancesKnowledge (“head” vs. “world”)                   Knowledge in the   Property                                   ...
Affordances "Hypermedia is defined by the presence of application control information embedded within, or as a layer abov...
Affordances "Hypermedia is defined by the presence of application control information embedded within, or as a layer abov...
AffordancesAffordances   makeHypermedia possible.                Layer 7 Confidential   21
Affordances      Hypermedia     can provide aRich Set of Affordances                     Layer 7 Confidential   22
Maze+XML       Design #1:A big pile of Affordances                      Layer 7 Confidential   23
Maze+XML Maze+XML media type First design in late 2010, registered w/ IANA 2011 “…an XML data format for sharing maze s...
Maze+XMLMessage           Layer 7 Confidential   25
Maze+XMLServer          Layer 7 Confidential   26
Maze+XMLClient          Layer 7 Confidential   27
Maze+XMLClient          Layer 7 Confidential   28
Maze+XMLClient          Layer 7 Confidential   29
Maze+XMLClient Code               Layer 7 Confidential   30
Maze+XMLIn the wild…                Layer 7 Confidential   31
Maze+XML Darrel Miller “A good example of using link relations to convey domain specific semantics.” “Has been a good t...
Maze+XMLDarrel Miller – C#                      Layer 7 Confidential   33
Maze+XML Yannick Loiseau “I can say that a non-restful architecture would have been a lot harder to deal with in bash, b...
Maze+XMLYannick Loiseau - Python                            Layer 7 Confidential   35
Maze+XMLYannick Loiseau - Bash                          Layer 7 Confidential   36
Maze+XML Characteristics - Read-Only navigational links - Limited set of identifiers - Domain specific Benefits - Simple...
H-Factors“Pardon me, did you say „links‟?”                           Layer 7 Confidential   38
H-Factors“The H Factor of a media-type is a measure of the level of hypermedia support within that media-type.”“H Factor...
H-FactorsAnalyzing Media Types                        Layer 7 Confidential   40
H-FactorsAnalyzing Media Types                        Layer 7 Confidential   41
H-FactorsAnalyzing Media Types                        Layer 7 Confidential   42
H-FactorsThere are five LINK Factors (LO, LE, LT, LI, LN)There are four CONTROL Factors (CR, CU, CM, CL)                ...
H-FactorsThere are five LINK Factors (LO, LE, LT, LI, LN)There are four CONTROL Factors (CR, CU, CM, CL)                ...
H-FactorsLinking Outbound Links (LO)                        Layer 7 Confidential   45
H-FactorsLinking Outbound Links (LO) Embedded Links (LE)                        Layer 7 Confidential   46
H-FactorsLinking Outbound Links (LO) Embedded Links (LE) Templated Links (LT)                         Layer 7 Confident...
H-FactorsLinking Outbound Links (LO) Embedded Links (LE) Templated Links (LT) Idempotent Links (LI)                   ...
H-FactorsLinking Outbound Links (LO) Embedded Links (LE) Templated Links (LT) Idempotent Links (LI) Non-Idempotent Li...
H-FactorsThere are five LINK Factors (LO, LE, LT, LI, LN)There are four CONTROL Factors (CR, CU, CM, CL)                ...
H-FactorsControl Request Controls (CR)                          Layer 7 Confidential   51
H-FactorsControl Request Controls (CR) Update Controls (CU)                          Layer 7 Confidential   52
H-FactorsControl Request Controls (CR) Update Controls (CU) Method Controls (CM)                          Layer 7 Confi...
H-FactorsControl Request Controls (CR) Update Controls (CU) Method Controls (CM) Link Controls (CL)                   ...
H-FactorsA pre-defined collection of H-Factors is called a “Media Type”Each media type has it’s own “H-Factor” signature...
H-FactorsH-Factors document  the Affordances       of the    Media Type                     Layer 7 Confidential   56
H-Factors“OK, media types, affordances, I see…                             Layer 7 Confidential   57
Collection+JSON         Design #2:A read/write hypermedia type                       Layer 7 Confidential   58
Collection+JSON Collection+JSON media type First designs in early 2011, registered w/ IANA mid 2011 “…a JSON-based read...
Collection+JSONMessage                Layer 7 Confidential   60
Collection+JSONMessage                Layer 7 Confidential   61
Collection+JSONMessage                Layer 7 Confidential   62
Collection+JSONMessage                Layer 7 Confidential   63
Collection+JSONMessage                Layer 7 Confidential   64
Collection+JSONServer               Layer 7 Confidential   65
Collection+JSONServer               Layer 7 Confidential   66
Collection+JSONServer               Layer 7 Confidential   67
Collection+JSONClient Code                    Layer 7 Confidential   68
Collection+JSONClient Code                    Layer 7 Confidential   69
Collection+JSONClient Code                    Layer 7 Confidential   70
Collection+JSONClient App                   Layer 7 Confidential   71
Collection+JSONClient App                   Layer 7 Confidential   72
Collection+JSONIn the wild…               Layer 7 Confidential   73
Collection+JSON Nokia Research - Live Mixed Reality - Vlad Stribu “[Collection+JSON] … allows us to develop authoring to...
Collection+JSON Nokia Research - Live Mixed Reality - Vlad Stribu “Collection+JSON was close enough to what we were look...
Collection+JSON CloudApp – Larry Marburger “CloudApp allows you to share images, links, music, videos and files.” “[Due...
Collection+JSON ember.js – Yehuda Katz “A framework for creating ambitious applications.” “By default, its somewhat rep...
Collection+JSON Characteristics - Read/Write w/ Templates - Small set of link identifiers - General “List Domain” handler...
Affordance Aspects“So, are all affordances essentially             the same?”                            Layer 7 Confident...
Affordance Aspects“For the purposes of applying affordances to hypermedia, there are four important aspects to consider” ...
Affordance AspectsSafeThe HTTP protocol supports a number of "safe" actions such as HEAD, and GET.                      ...
Affordance AspectsSafeThe HTTP protocol supports a number of "safe" actions such as HEAD, and GET.The HTTP methods PUT,...
Affordance AspectsIdempotentWhen an HTML:FORM element has the METHOD property set to "get" it represents an idempotent a...
Affordance AspectsIdempotentWhen an HTML:FORM element has the METHOD property set to "get" it represents an idempotent a...
Affordance AspectsMutabilityHTML:FORM affords mutability                                  Layer 7 Confidential   85
Affordance AspectsMutabilityHTML:FORM affords mutabilityHTML:LINK is immutable                                   Layer ...
Affordance AspectsTransclusionHTML:IMG affords transclusion                                   Layer 7 Confidential   87
Affordance AspectsTransclusionHTML:IMG affords transclusionHTML:A does not                                   Layer 7 Co...
Affordance AspectsHowever, this single affordance is notvery usable.                                Layer 7 Confidential ...
Affordance AspectsMedia types should be  usable              Layer 7 Confidential   90
Affordance AspectsMessagesshould be usable             Layer 7 Confidential   91
Affordance Aspects  APIsshould be usable             Layer 7 Confidential   92
ALPS for HTML          Design #3:Aspects, Factors, Abstractions                        Layer 7 Confidential   93
ALPS for HTML ALPS profile URI First designs in early 2011 (not registered) “The purpose of Application-Level Profile S...
ALPS for HTML ALPS profile URI Multiple parties building their own client or server applications without seeing each oth...
ALPS for HTMLMessages                Layer 7 Confidential   96
ALPS for HTMLMessages                Layer 7 Confidential   97
ALPS for HTMLMessages                Layer 7 Confidential   98
ALPS for HTMLServer Code                   Layer 7 Confidential   99
ALPS for HTMLClient Code                  Layer 7 Confidential   100
ALPS for HTMLClient App                 Layer 7 Confidential   101
ALPS for HTMLClient Bot                 Layer 7 Confidential   102
ALPS for HTMLClient Bot                 Layer 7 Confidential   103
ALPS for HTMLClient Bot                 Layer 7 Confidential   104
ALPS for HTML“In the wild…”                 Layer 7 Confidential   105
ALPS for HTMLRstat.us – Carol Nichols “There are two things that make rstat.us special: simplicity and openness.” “[S]in...
ALPS for HTMLRstat.us – Carol Nichols                               Layer 7 Confidential   107
ALPS for HTMLRstat.us – Carol Nichols                               Layer 7 Confidential   108
ALPS for HTML Characteristics - Domain Semantics Only - Media-type agnostic Benefits - Focused on problem domain - Treat...
ALPS for HTML“If HTML is not the only media-type            we need…”                           Layer 7 Confidential   110
ALPS for HTML“How do you choose?”                   Layer 7 Confidential   111
MethodologyMapping your domain to HTTP                     Layer 7 Confidential   112
MethodologyDesigning messages is the primary workFocus on mapping to payloads, not identifiersSurvey existing media typ...
MethodologyStart with a format (XML, JSON, HTML, etc.)You might need to support more than oneDon’t assume you can “cros...
MethodologySelect your other design elements as needed                                      Layer 7 Confidential   115
MethodologyRepresent State, not ObjectsRemember both data and transitionsCraft lots of messagesPro Tip: you can never ...
MethodologyWhen you are sure you have:The proper formatThe right H-Factor signatureThe correct mapping of domain to mes...
MethodologyYou can start writing     the code                        Layer 7 Confidential   118
MethodologyBecause…             Layer 7 Confidential   119
Methodology  The code is onlythe implementation                     Layer 7 Confidential   120
Methodology  The code is onlythe implementationThe media type is   the design.                     Layer 7 Confidential   ...
MethodologyAnd if you get the design         right...                       Layer 7 Confidential   122
MethodologyYour users will be able     to do things                      Layer 7 Confidential   123
MethodologyYour users will be able     to do things                      Layer 7 Confidential   124
MethodologyYour users will be able     to do things you never imagined                      Layer 7 Confidential   125
Mike AmundsenThe Costs and Benefits ofBuilding Hypermedia APIs(with Node.js)      @mamund                      Layer 7 Con...
The Cost and Benefits of Building Hypermedia APIs (with Node.js) from QconSF
Upcoming SlideShare
Loading in …5
×

The Cost and Benefits of Building Hypermedia APIs (with Node.js) from QconSF

3,554 views

Published on

Real-Life Stories on Building Hypermedia APIs - Mike Amundsen, Principal API Architect, Layer 7 Technologies

The Cost and Benefits of Building Hypermedia APIs (with Node.js) from QconSF

  1. 1. Mike AmundsenThe Costs and Benefits ofBuilding Hypermedia APIs(with Node.js) Layer 7 Confidential 1
  2. 2. Mike AmundsenAuthorPresenterSoftware ExplorerPrincipal API Architect Layer 7 Confidential 2
  3. 3. OK, let‟s get started… Layer 7 Confidential 3
  4. 4. Theonia "a looking at, viewing, beholding” Layer 7 Confidential 4
  5. 5. Theory "a looking at, viewing, beholding” Layer 7 Confidential 5
  6. 6. Praxis “doing” Layer 7 Confidential 6
  7. 7. Practice “doing” Layer 7 Confidential 7
  8. 8. First, a lesson to remember from Donald Norman… Layer 7 Confidential 8
  9. 9. 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 Layer 7 Confidential 10
  10. 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 Layer 7 Confidential 11
  11. 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 Layer 7 Confidential 12
  12. 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 Layer 7 Confidential 13
  13. 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 Layer 7 Confidential 14
  14. 14. Some background… Layer 7 Confidential 15
  15. 15. 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 Layer 7 Confidential 16
  16. 16. Affordances Seven Stages of ActionThe Design of Everyday Things, 1988- Donald Norman Layer 7 Confidential 17
  17. 17. AffordancesKnowledge (“head” vs. “world”) Knowledge in the Property Knowledge in the Head World Learning not required. Interpretation Requires learning, which substitutes for learning. can be considerable. How easy it is to Learning is made easier if interpret information is Learning there is meaning of the world depends structure to the material (or upon how well it if there is a good mental exploits natural model). mappings and constraints. Tends to be slowed up Efficiency by the need to find and Can be very efficient of use interpret the external information. Ease of use at first High Low encounterApril 17, 2012 APIs to Affordances : WS-REST 2012 18 Layer 7 Confidential 18
  18. 18. 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 Designof Network-based Software, 2001- Roy T. Fielding Layer 7 Confidential 19
  19. 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 Designof Network-based Software, 2001- Roy T. Fielding Layer 7 Confidential 20
  20. 20. AffordancesAffordances makeHypermedia possible. Layer 7 Confidential 21
  21. 21. Affordances Hypermedia can provide aRich Set of Affordances Layer 7 Confidential 22
  22. 22. Maze+XML Design #1:A big pile of Affordances Layer 7 Confidential 23
  23. 23. 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 Layer 7 Confidential 24
  24. 24. Maze+XMLMessage Layer 7 Confidential 25
  25. 25. Maze+XMLServer Layer 7 Confidential 26
  26. 26. Maze+XMLClient Layer 7 Confidential 27
  27. 27. Maze+XMLClient Layer 7 Confidential 28
  28. 28. Maze+XMLClient Layer 7 Confidential 29
  29. 29. Maze+XMLClient Code Layer 7 Confidential 30
  30. 30. Maze+XMLIn the wild… Layer 7 Confidential 31
  31. 31. 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.” Layer 7 Confidential 32
  32. 32. Maze+XMLDarrel Miller – C# Layer 7 Confidential 33
  33. 33. Maze+XML 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…” Layer 7 Confidential 34
  34. 34. Maze+XMLYannick Loiseau - Python Layer 7 Confidential 35
  35. 35. Maze+XMLYannick Loiseau - Bash Layer 7 Confidential 36
  36. 36. 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 Layer 7 Confidential 37
  37. 37. H-Factors“Pardon me, did you say „links‟?” Layer 7 Confidential 38
  38. 38. H-Factors“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.”REST: From Research to Practice :Hypermedia Types, 2011- Mike Amundsen Layer 7 Confidential 39
  39. 39. H-FactorsAnalyzing Media Types Layer 7 Confidential 40
  40. 40. H-FactorsAnalyzing Media Types Layer 7 Confidential 41
  41. 41. H-FactorsAnalyzing Media Types Layer 7 Confidential 42
  42. 42. H-FactorsThere are five LINK Factors (LO, LE, LT, LI, LN)There are four CONTROL Factors (CR, CU, CM, CL) Layer 7 Confidential 43
  43. 43. H-FactorsThere are five LINK Factors (LO, LE, LT, LI, LN)There are four CONTROL Factors (CR, CU, CM, CL) Layer 7 Confidential 44
  44. 44. H-FactorsLinking Outbound Links (LO) Layer 7 Confidential 45
  45. 45. H-FactorsLinking Outbound Links (LO) Embedded Links (LE) Layer 7 Confidential 46
  46. 46. H-FactorsLinking Outbound Links (LO) Embedded Links (LE) Templated Links (LT) Layer 7 Confidential 47
  47. 47. H-FactorsLinking Outbound Links (LO) Embedded Links (LE) Templated Links (LT) Idempotent Links (LI) Layer 7 Confidential 48
  48. 48. H-FactorsLinking Outbound Links (LO) Embedded Links (LE) Templated Links (LT) Idempotent Links (LI) Non-Idempotent Links (LN) Layer 7 Confidential 49
  49. 49. H-FactorsThere are five LINK Factors (LO, LE, LT, LI, LN)There are four CONTROL Factors (CR, CU, CM, CL) Layer 7 Confidential 50
  50. 50. H-FactorsControl Request Controls (CR) Layer 7 Confidential 51
  51. 51. H-FactorsControl Request Controls (CR) Update Controls (CU) Layer 7 Confidential 52
  52. 52. H-FactorsControl Request Controls (CR) Update Controls (CU) Method Controls (CM) Layer 7 Confidential 53
  53. 53. H-FactorsControl Request Controls (CR) Update Controls (CU) Method Controls (CM) Link Controls (CL) Layer 7 Confidential 54
  54. 54. H-FactorsA pre-defined collection of H-Factors is called a “Media Type”Each media type has it’s own “H-Factor” signature. Layer 7 Confidential 55
  55. 55. H-FactorsH-Factors document the Affordances of the Media Type Layer 7 Confidential 56
  56. 56. H-Factors“OK, media types, affordances, I see… Layer 7 Confidential 57
  57. 57. Collection+JSON Design #2:A read/write hypermedia type Layer 7 Confidential 58
  58. 58. 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 Layer 7 Confidential 59
  59. 59. Collection+JSONMessage Layer 7 Confidential 60
  60. 60. Collection+JSONMessage Layer 7 Confidential 61
  61. 61. Collection+JSONMessage Layer 7 Confidential 62
  62. 62. Collection+JSONMessage Layer 7 Confidential 63
  63. 63. Collection+JSONMessage Layer 7 Confidential 64
  64. 64. Collection+JSONServer Layer 7 Confidential 65
  65. 65. Collection+JSONServer Layer 7 Confidential 66
  66. 66. Collection+JSONServer Layer 7 Confidential 67
  67. 67. Collection+JSONClient Code Layer 7 Confidential 68
  68. 68. Collection+JSONClient Code Layer 7 Confidential 69
  69. 69. Collection+JSONClient Code Layer 7 Confidential 70
  70. 70. Collection+JSONClient App Layer 7 Confidential 71
  71. 71. Collection+JSONClient App Layer 7 Confidential 72
  72. 72. Collection+JSONIn the wild… Layer 7 Confidential 73
  73. 73. 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.” Layer 7 Confidential 74
  74. 74. 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…” Layer 7 Confidential 75
  75. 75. 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 whos making amazing progress.” Layer 7 Confidential 76
  76. 76. Collection+JSON ember.js – Yehuda Katz “A framework for creating ambitious applications.” “By default, its 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.” Layer 7 Confidential 77
  77. 77. 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 Layer 7 Confidential 78
  78. 78. Affordance Aspects“So, are all affordances essentially the same?” Layer 7 Confidential 79
  79. 79. Affordance Aspects“For the purposes of applying affordances to hypermedia, there are four important aspects to consider” Layer 7 Confidential 80
  80. 80. Affordance AspectsSafeThe HTTP protocol supports a number of "safe" actions such as HEAD, and GET. Layer 7 Confidential 81
  81. 81. 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. Layer 7 Confidential 82
  82. 82. Affordance AspectsIdempotentWhen an HTML:FORM element has the METHOD property set to "get" it represents an idempotent action. Layer 7 Confidential 83
  83. 83. 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. Layer 7 Confidential 84
  84. 84. Affordance AspectsMutabilityHTML:FORM affords mutability Layer 7 Confidential 85
  85. 85. Affordance AspectsMutabilityHTML:FORM affords mutabilityHTML:LINK is immutable Layer 7 Confidential 86
  86. 86. Affordance AspectsTransclusionHTML:IMG affords transclusion Layer 7 Confidential 87
  87. 87. Affordance AspectsTransclusionHTML:IMG affords transclusionHTML:A does not Layer 7 Confidential 88
  88. 88. Affordance AspectsHowever, this single affordance is notvery usable. Layer 7 Confidential 89
  89. 89. Affordance AspectsMedia types should be usable Layer 7 Confidential 90
  90. 90. Affordance AspectsMessagesshould be usable Layer 7 Confidential 91
  91. 91. Affordance Aspects APIsshould be usable Layer 7 Confidential 92
  92. 92. ALPS for HTML Design #3:Aspects, Factors, Abstractions Layer 7 Confidential 93
  93. 93. 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.” Layer 7 Confidential 94
  94. 94. ALPS for HTML ALPS profile URI Multiple parties building their own client or server applications without seeing each others 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. Layer 7 Confidential 95
  95. 95. ALPS for HTMLMessages Layer 7 Confidential 96
  96. 96. ALPS for HTMLMessages Layer 7 Confidential 97
  97. 97. ALPS for HTMLMessages Layer 7 Confidential 98
  98. 98. ALPS for HTMLServer Code Layer 7 Confidential 99
  99. 99. ALPS for HTMLClient Code Layer 7 Confidential 100
  100. 100. ALPS for HTMLClient App Layer 7 Confidential 101
  101. 101. ALPS for HTMLClient Bot Layer 7 Confidential 102
  102. 102. ALPS for HTMLClient Bot Layer 7 Confidential 103
  103. 103. ALPS for HTMLClient Bot Layer 7 Confidential 104
  104. 104. ALPS for HTML“In the wild…” Layer 7 Confidential 105
  105. 105. ALPS for HTMLRstat.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.” Layer 7 Confidential 106
  106. 106. ALPS for HTMLRstat.us – Carol Nichols Layer 7 Confidential 107
  107. 107. ALPS for HTMLRstat.us – Carol Nichols Layer 7 Confidential 108
  108. 108. 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 Layer 7 Confidential 109
  109. 109. ALPS for HTML“If HTML is not the only media-type we need…” Layer 7 Confidential 110
  110. 110. ALPS for HTML“How do you choose?” Layer 7 Confidential 111
  111. 111. MethodologyMapping your domain to HTTP Layer 7 Confidential 112
  112. 112. Methodology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. Layer 7 Confidential 113
  113. 113. Methodology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. Layer 7 Confidential 114
  114. 114. MethodologySelect your other design elements as needed Layer 7 Confidential 115
  115. 115. MethodologyRepresent State, not ObjectsRemember both data and transitionsCraft lots of messagesPro Tip: you can never have enough messages Layer 7 Confidential 116
  116. 116. MethodologyWhen 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… Layer 7 Confidential 117
  117. 117. MethodologyYou can start writing the code Layer 7 Confidential 118
  118. 118. MethodologyBecause… Layer 7 Confidential 119
  119. 119. Methodology The code is onlythe implementation Layer 7 Confidential 120
  120. 120. Methodology The code is onlythe implementationThe media type is the design. Layer 7 Confidential 121
  121. 121. MethodologyAnd if you get the design right... Layer 7 Confidential 122
  122. 122. MethodologyYour users will be able to do things Layer 7 Confidential 123
  123. 123. MethodologyYour users will be able to do things Layer 7 Confidential 124
  124. 124. MethodologyYour users will be able to do things you never imagined Layer 7 Confidential 125
  125. 125. Mike AmundsenThe Costs and Benefits ofBuilding Hypermedia APIs(with Node.js) @mamund Layer 7 Confidential 126

×