Your SlideShare is downloading. ×
1Designing and Implementing Hypermedia APIsQCon New York 2013 Mike Amundsen,Principal API ArchitectLayer 7 Techologies@ma...
2Mike Amundsen Author, Web Architect, Presenter Principal API Architect Building Hypermedia APIs with HTML5 and Node R...
3Agenda Hypermedia – the Short Story (15:00) Designing Hypermedia APIs (10:00 ) Hack a Hypermedia API (30:00) Implemen...
4Reminders Bells & Whistles Off Feel free to stretch, move about as needed Ask Questions Enjoy the Session
5HYPERMEDIA –THE SHORT STORY
6Atlas holds the weight of the world on his shoulders…
7On the Shoulders of Giants
8Vannevar Bush Memex, 1945 Key project leader on the Manhattan Project to build the first nuclearbomb. “ A memex …is an...
9Douglas Engelbart Computer mouse, 1965 Key to creating the ARPANET while at Stanford Research, Institue (SRI). “Augmen...
10Ted Nelson Hypertext, 1963 Identified and popularized early “cyber-culture” in 1979 book “ComputerLib/Machine Dreams”...
11James J. Gibson “The Ecological Approach to Visual Perception” (1986) Coined the term “affordance” Environments provi...
12Donald Norman The Design of Everyday Things, 1988 Action Lifecycle, Seven Stages of Action “In the world” and “In the...
13Tim Berners-Lee Tim Berners-Lee @ CERN 1980 ENQUIRE in 1984 (hypertext database) Information Mgmt: A Proposal to CERN...
14Roy T. Fielding Architectural Styles and theDesign of Network-based Software Architectures, 2000 Created “REST” Key i...
15On the Shoulders of Giants
16Hypermedia Factors
17H-FactorsAnalyzing Media Types
18H-FactorsAnalyzing Media Types
19H-FactorsAnalyzing Media Types
20H-Factors There are five LINK Factors(LO, LE, LT, LI, LN) There are four CONTROL Factors(CR, CU, CM, CL)
21H-Factors There are five LINK Factors(LO, LE, LT, LI, LN) There are four CONTROL Factors(CR, CU, CM, CL)
22H-FactorsLinkingOutbound Links (LO)
23H-FactorsLinkingOutbound Links (LO)Embedded Links (LE)
24H-FactorsLinkingOutbound Links (LO)Embedded Links (LE)Templated Links (LT)
25H-FactorsLinkingOutbound Links (LO)Embedded Links (LE)Templated Links (LT)Idempotent Links (LI)
26H-FactorsLinkingOutbound Links (LO)Embedded Links (LE)Templated Links (LT)Idempotent Links (LI)Non-Idempotent Links...
27H-Factors There are five LINK Factors(LO, LE, LT, LI, LN) There are four CONTROL Factors(CR, CU, CM, CL)
28H-FactorsControlRequest Controls (CR)
29H-FactorsControlRequest Controls (CR)Update Controls (CU)
30H-FactorsControlRequest Controls (CR)Update Controls (CU)Method Controls (CM)
31H-FactorsControlRequest Controls (CR)Update Controls (CU)Method Controls (CM)Link Controls (CL)
32H-Factors A collection of H-Factors is called a Hypermedia Type By identifying H-Factors, you discover the “Hypermedia...
33Three Pillars of Hypermedia Design
34
35Three Pillars of Hypermedia Design Structure Semantics (XML, JSON, YAML, etc.) Protocol Semantics (HTTP, WS, FTP, etc....
36Three Pillars of Hypermedia DesignStructure Semantics How you communicate the layout of the response Simple structure...
37Three Pillars of Hypermedia DesignProtocol Semantics How you communicate the possible actions in the response Simple ...
38Three Pillars of Hypermedia DesignDomain Semantics How you communicate the domain-specific details in the response Si...
39Three Pillars of Hypermedia DesignOn the Web, media types don’t define a solution,they describe a problem domain
40Three Pillars of Hypermedia DesignThe more descriptive the media type,the easier it is to talk about the problem.
41DESIGNING HYPERMEDIA APIS
42Designing Hypermedia APIsLet’s describe the Class Scheduling domain…
43Designing Hypermedia APIsLet’s describe the Class Scheduling domain…and let’s keep it real simple today.
44application/vnd.apiacademy-scheduling+xml
45Domain Eleven data elements:- courseCapacity,courseDescription,courseId, courseName,scheduleId, scheduleSlot,studentId,...
46Designing Hypermedia APIsLet’s map the actions to (at least) one Web protocol…
47Designing Hypermedia APIsLet’s map the actions to (at least) one Web protocol…We could use HTTP, WebSockets, XMPP…
48Designing Hypermedia APIsLet’s map the actions to (at least) one Web protocol…We could use HTTP, WebSockets, XMPP…But, o...
49Protocol Map eight actions:- add, update, remove,read, list, filter,assign, unassign To four HTTP methods:- GET, POST,...
50Designing Hypermedia APIsLet’s document the possible data elementsfor each action, too.
51Data elements with actions…
52Designing Hypermedia APIsFinally, let’s design a single messagethat can carry all that information…
53Structure Nine Elements- root, actions, link, list,item, template, display,data, error Six Attributes- href, name, act...
54Designing Hypermedia APIsNote we covered the three key aspectsto each message design…
55Designing Hypermedia APIsNote we covered the three key aspectsto each message design…Structure
56Designing Hypermedia APIsNote we covered the three key aspectsto each message design…StructureProtocol
57Designing Hypermedia APIsNote we covered the three key aspectsto each message design…StructureProtocolDomain
58Now let’s see some examples…
59
60Let’s Design a Hypermedia API!
61IMPLEMENTING HYPERMEDIASERVERS
62Implementing Hypermedia Servers Components- Storage- Object Model/Processing Connectors- Representation- Routing/Reque...
63Component != Connector
64ComponentDatabaseFile SystemMessage QueueTransaction ManagerSource Code
65Component == Private
66
67ConnectorWeb ServerBrowser AgentProxy ServerShared Cache
68Connector == Public
69
70Client ServerConnectorsComponentsThe Web
71Representation Layer
72Representation Layer Representation happens in the Connector HTTP supports content negotiation- Accept- Content-Type ...
73Implementing Hypermedia Servers Storage Handles direct access to stored content (if any) Database (MySQL, SQLServer, ...
74Implementing Hypermedia Servers Components Handles business rules and any processing/computing, etc. Validate data/ob...
75Implementing Hypermedia Servers Representation Handles converting internal objects into external media type *NOT* a s...
76Implementing Hypermedia Servers Routing Handles incoming requests, routes to appropriate method/handler Thin veneer b...
77Let’s Build a Hypermedia Server!
78Summary : Implementing Hypermedia Servers Components- Storage (DB, FileSys, external)- Object Model/Processing (objects...
79BUILDING HYPERMEDIACLIENTS
80Building Hypermedia Clients Hypermedia clients for humans Hypermedia clients for machines
81Hypermedia for Humans
82What is a Hypermedia for Humans client?A client that is able todetermine possible protocol-level choices at runtimeusing...
83Some things to keep in mind…Hypermedia clients are based on the “Action Lifecycle”
84Some things to keep in mind…http://en.wikipedia.org/wiki/Human_action_cycle
85Some things to keep in mind…Oh!, I almost forgot…
86Hypermedia clientsTypically hypermedia clients have almost no long-term memory.
87Hypermedia clientsTypically hypermedia clients have almost no long-term memory.Hypermedia clients’ memories last for a s...
88Hypermedia clientsTypically hypermedia clients have almost no long-term memory.Hypermedia clients’ memories last for a s...
89Faithful Hypermedia Clients (FHCs) FHCs simply pass along whatever the server returns; usually to a human. FHCs MAY ma...
90Guide for implementing an FHC Process the structure semantics in order to render view Process the protocol semantics i...
91Process the structure semantics
92Process the structure semantics
93Process the structure semantics
94Process protocol semantics
95Process protocol semantics
96Process protocol semantics
97Process domain semantics
98Process domain semantics
99Summary for the Class Schedule FHC Structure Semantics- Take advantage of client-side XSLT- Build XSL processor for vnd...
100Advantages of hypermedia clients for humans Flexibility to support a wide range of non-breaking domain-level changes- ...
101Drawbacks of hypermedia clients for humans SoC can mean extra work for clients- Need to keep structure, protocol, doma...
102Hypermedia for MachinesHypermedia for Machines
103What is a hypermedia machine client?A client that is able toprocess responses,locate protocol actions, andmake domain-l...
104What is a hypermedia machine client?A client that is able toprocess responses,locate protocol actions, andmake domain-l...
105Agent Hypermedia Clients (AHCs) AHCs can process all three levels of messages:- Structure- Protocol- Domain AHCs MUST...
106Guide for implementing an AHC Process the structure semantics in order to know what’s “there” Process the protocol se...
107Maze+XML Media Type
108Maze+XML FHC
109The Maze+XML AHC
110“Teach” AHC about mazes
111Process the structure semantics
112Process the protocol semantics
113Process the domain semantics
114Summary for Maze+XML AHC Structure Semantics- XML DOM Parser + recognizing five elements (maze, collection, item,cell,...
115Advantages of hypermedia clients for machines Ability to hand off tedious work to “smart” machine Using “generic” med...
116Drawbacks of hypermedia clients for machines Making machines “smart” takes time, esp. for non-trivial tasks Some chan...
117Let’s Build a Hypermedia Client!
118Summary : Building Hypermedia Clients Hypermedia clients for humans (FHC)- A client that is able to determine possible...
119NOW WHAT?
120Now What? Hypermedia goes back more than ½ a century Remember the H-Factors (LO, LE, LT, LI, LN, CR, CU, CM, CL) Alw...
121Let’s Grow the Hypermedia Web!
122Available Server Projects YouTypeItWePostIt (:8080/api/)- https://github.com/mamund/rwa Maze+XML (:8181)- https://git...
123Designing and Implementing Hypermedia APIsQCon New York 2013 Mike Amundsen,Principal API ArchitectLayer 7 Techologies@...
Upcoming SlideShare
Loading in...5
×

Designing & Implementing Hypermedia APIs – Mike Amundsen, Principal API Architect, Layer 7

1,590

Published on

Principal API Architect Mike Amundsen presented this talk at QConn New York 2013.

Hypermedia APIs are getting some buzz. But what are they, really? What is the difference between common URI-based CRUD API designs and hypermedia-style APIs? How do you implement a hypermedia API and when does it make sense to use a hypermedia design instead of a CRUD-based approach? Based on the Mike Amundsen's multi-part InfoQ article series of the same name, this fast paced, hands-on four-hour workshop shows attendees how to design a hypermedia style API, how to implement a server that supports varying hypermedia responses, and how to build clients that can take advantage of hypermedia. Additional time will be spent exploring when clients break and how reliance on hypermedia can reduce the need for re-coding and re-deploying client applications while still supporting new features in the API. Hands-on labs include authoring a hypermedia format for your API, designing server-side components that can emit hypermedia responses, and deciding on which client-side style of hypermedia fits best for your needs. A final challenge will be to update the server-side responses with new features that do not break existing hypermedia clients.

Published in: Technology

Transcript of "Designing & Implementing Hypermedia APIs – Mike Amundsen, Principal API Architect, Layer 7"

  1. 1. 1Designing and Implementing Hypermedia APIsQCon New York 2013 Mike Amundsen,Principal API ArchitectLayer 7 Techologies@mamund#HyperQCon
  2. 2. 2Mike Amundsen Author, Web Architect, Presenter Principal API Architect Building Hypermedia APIs with HTML5 and Node RESTful Web APIs (Richardson, Amundsen, Ruby)
  3. 3. 3Agenda Hypermedia – the Short Story (15:00) Designing Hypermedia APIs (10:00 ) Hack a Hypermedia API (30:00) Implementing Hypermedia Servers (10 :00) Hack a Hypermedia Server (45:00) Building Hypermedia Clients (10:00) Hack a Hypermedia Client (45:00) Now What? (15:00)
  4. 4. 4Reminders Bells & Whistles Off Feel free to stretch, move about as needed Ask Questions Enjoy the Session
  5. 5. 5HYPERMEDIA –THE SHORT STORY
  6. 6. 6Atlas holds the weight of the world on his shoulders…
  7. 7. 7On the Shoulders of Giants
  8. 8. 8Vannevar Bush Memex, 1945 Key project leader on the Manhattan Project to build the first nuclearbomb. “ A memex …is an enlarged intimate supplement to … memory.” “With one item in its grasp, [the mind] snaps instantly to the next that issuggested by the association of thoughts, in accordance with someintricate web of trails carried by the cells of the brain.”
  9. 9. 9Douglas Engelbart Computer mouse, 1965 Key to creating the ARPANET while at Stanford Research, Institue (SRI). “Augmenting Human Intellect”, 1962 “[A] new and systematic approach to improving the intellectual effectiveness ofthe individual human being … One of the tools that shows the greatestimmediate promise is the computer.”
  10. 10. 10Ted Nelson Hypertext, 1963 Identified and popularized early “cyber-culture” in 1979 book “ComputerLib/Machine Dreams” “If computers are the wave of the future, displays are the surfboards.”
  11. 11. 11James J. Gibson “The Ecological Approach to Visual Perception” (1986) Coined the term “affordance” Environments provide niches of appropriate affordances Animals survive/thrive when they can exploit the affordances in their niche“An affordance is a quality of an object, or an environment, which allows anindividual to perform an action.”
  12. 12. 12Donald Norman The Design of Everyday Things, 1988 Action Lifecycle, Seven Stages of Action “In the world” and “In the head” “Simplification is as much in the mind as it is in the device.” “Design is really an act of communication.”
  13. 13. 13Tim Berners-Lee Tim Berners-Lee @ CERN 1980 ENQUIRE in 1984 (hypertext database) Information Mgmt: A Proposal to CERN in 1989 HTTP (1992), HTML (1993), RDF (2004) “A way to link and access information of various kinds as a web of nodes in which theuser can browse at will.”
  14. 14. 14Roy T. Fielding Architectural Styles and theDesign of Network-based Software Architectures, 2000 Created “REST” Key in the startup and operation of the “Apache Foundation” Representations and Hypermedia “A resource is not the thing that is transferred across the wire or picked up off thedisk or seen from afar while walking your dog. Each of those is only a representation.Do I think of a different identifier every time I see my dog, or do I simply think of mydog as one identity and experience many representations of that identity over time(and on into memory and imagination)?
  15. 15. 15On the Shoulders of Giants
  16. 16. 16Hypermedia Factors
  17. 17. 17H-FactorsAnalyzing Media Types
  18. 18. 18H-FactorsAnalyzing Media Types
  19. 19. 19H-FactorsAnalyzing Media Types
  20. 20. 20H-Factors There are five LINK Factors(LO, LE, LT, LI, LN) There are four CONTROL Factors(CR, CU, CM, CL)
  21. 21. 21H-Factors There are five LINK Factors(LO, LE, LT, LI, LN) There are four CONTROL Factors(CR, CU, CM, CL)
  22. 22. 22H-FactorsLinkingOutbound Links (LO)
  23. 23. 23H-FactorsLinkingOutbound Links (LO)Embedded Links (LE)
  24. 24. 24H-FactorsLinkingOutbound Links (LO)Embedded Links (LE)Templated Links (LT)
  25. 25. 25H-FactorsLinkingOutbound Links (LO)Embedded Links (LE)Templated Links (LT)Idempotent Links (LI)
  26. 26. 26H-FactorsLinkingOutbound Links (LO)Embedded Links (LE)Templated Links (LT)Idempotent Links (LI)Non-Idempotent Links (LN)
  27. 27. 27H-Factors There are five LINK Factors(LO, LE, LT, LI, LN) There are four CONTROL Factors(CR, CU, CM, CL)
  28. 28. 28H-FactorsControlRequest Controls (CR)
  29. 29. 29H-FactorsControlRequest Controls (CR)Update Controls (CU)
  30. 30. 30H-FactorsControlRequest Controls (CR)Update Controls (CU)Method Controls (CM)
  31. 31. 31H-FactorsControlRequest Controls (CR)Update Controls (CU)Method Controls (CM)Link Controls (CL)
  32. 32. 32H-Factors A collection of H-Factors is called a Hypermedia Type By identifying H-Factors, you discover the “Hypermedia signature” of media type.
  33. 33. 33Three Pillars of Hypermedia Design
  34. 34. 34
  35. 35. 35Three Pillars of Hypermedia Design Structure Semantics (XML, JSON, YAML, etc.) Protocol Semantics (HTTP, WS, FTP, etc.) Application Domain Semantics (students, courseName, scheduleId, etc.) All Web apps MUST support these somehow. What’s not in themessage, is in the source code instead.
  36. 36. 36Three Pillars of Hypermedia DesignStructure Semantics How you communicate the layout of the response Simple structures:- text/csv- application/xml- application/json Advanced structures- text/html- application/atom+xml- application/vnd.hal+json- application/vnd.collection+json
  37. 37. 37Three Pillars of Hypermedia DesignProtocol Semantics How you communicate the possible actions in the response Simple actions:- HTML.A- HTML.IMG- HTML.LINK Advanced actions:- HTML.FORM@get- HTML.FORM@post- ATOM.LINK@edit- collection.queries.link@data[]
  38. 38. 38Three Pillars of Hypermedia DesignDomain Semantics How you communicate the domain-specific details in the response Simple domain-specifics:- MAZE: collection, cell- VOICEXML: assign, transfer, disconnect,- ATOM: feed, entry, content Advanced domain-specifics- HTML: @id, @name, @class, @rel- CJ: @id, @name, @value, @href- HAL: @rel, @name
  39. 39. 39Three Pillars of Hypermedia DesignOn the Web, media types don’t define a solution,they describe a problem domain
  40. 40. 40Three Pillars of Hypermedia DesignThe more descriptive the media type,the easier it is to talk about the problem.
  41. 41. 41DESIGNING HYPERMEDIA APIS
  42. 42. 42Designing Hypermedia APIsLet’s describe the Class Scheduling domain…
  43. 43. 43Designing Hypermedia APIsLet’s describe the Class Scheduling domain…and let’s keep it real simple today.
  44. 44. 44application/vnd.apiacademy-scheduling+xml
  45. 45. 45Domain Eleven data elements:- courseCapacity,courseDescription,courseId, courseName,scheduleId, scheduleSlot,studentId, studentName,studentStanding,teacherId, teacherName Eight actions:- add, update, remove,read, list, filter, assign,unassign Five identifiers:- home, course, student,teacher, schedule
  46. 46. 46Designing Hypermedia APIsLet’s map the actions to (at least) one Web protocol…
  47. 47. 47Designing Hypermedia APIsLet’s map the actions to (at least) one Web protocol…We could use HTTP, WebSockets, XMPP…
  48. 48. 48Designing Hypermedia APIsLet’s map the actions to (at least) one Web protocol…We could use HTTP, WebSockets, XMPP…But, of course, we’ll use HTTP today.
  49. 49. 49Protocol Map eight actions:- add, update, remove,read, list, filter,assign, unassign To four HTTP methods:- GET, POST,PUT, DELETE.
  50. 50. 50Designing Hypermedia APIsLet’s document the possible data elementsfor each action, too.
  51. 51. 51Data elements with actions…
  52. 52. 52Designing Hypermedia APIsFinally, let’s design a single messagethat can carry all that information…
  53. 53. 53Structure Nine Elements- root, actions, link, list,item, template, display,data, error Six Attributes- href, name, action,prompt, value, embed Four Data Types- ID, URI, TEXT,BOOLEAN
  54. 54. 54Designing Hypermedia APIsNote we covered the three key aspectsto each message design…
  55. 55. 55Designing Hypermedia APIsNote we covered the three key aspectsto each message design…Structure
  56. 56. 56Designing Hypermedia APIsNote we covered the three key aspectsto each message design…StructureProtocol
  57. 57. 57Designing Hypermedia APIsNote we covered the three key aspectsto each message design…StructureProtocolDomain
  58. 58. 58Now let’s see some examples…
  59. 59. 59
  60. 60. 60Let’s Design a Hypermedia API!
  61. 61. 61IMPLEMENTING HYPERMEDIASERVERS
  62. 62. 62Implementing Hypermedia Servers Components- Storage- Object Model/Processing Connectors- Representation- Routing/Request Handling
  63. 63. 63Component != Connector
  64. 64. 64ComponentDatabaseFile SystemMessage QueueTransaction ManagerSource Code
  65. 65. 65Component == Private
  66. 66. 66
  67. 67. 67ConnectorWeb ServerBrowser AgentProxy ServerShared Cache
  68. 68. 68Connector == Public
  69. 69. 69
  70. 70. 70Client ServerConnectorsComponentsThe Web
  71. 71. 71Representation Layer
  72. 72. 72Representation Layer Representation happens in the Connector HTTP supports content negotiation- Accept- Content-Type Differing clients (user-agents) === differing representations- Desktop- Browser- Tablet- Smartphone Be prepared to support multiple representations
  73. 73. 73Implementing Hypermedia Servers Storage Handles direct access to stored content (if any) Database (MySQL, SQLServer, Oracle, CouchDB, Mongo, etc.) File system (Local File I/O) External Service (Salesforce, Amazon, Azure, etc.) In-Memory (memcacheD, etc.) Advice for this event:- Keep it simple- Use in-memory array for starter, add perm storage later- Use existing APIs (see listing today)
  74. 74. 74Implementing Hypermedia Servers Components Handles business rules and any processing/computing, etc. Validate data/objects Create any defaults or related data/objects Enforce data integrity on writes Enforce ACLs on reads/writes (skip for today) Advice for this event:- Keep it simple- Consider read-only for today- Use existing APIs (see listing today)
  75. 75. 75Implementing Hypermedia Servers Representation Handles converting internal objects into external media type *NOT* a serializer Convert object graph into list/items Include protocol affordances (links & forms) Maps domain-specifics to appropriate elements/attributes/properties Advice for this event:- Keep it simple- Consider using an existing hypermedia type- Use existing APIs (see listing today)
  76. 76. 76Implementing Hypermedia Servers Routing Handles incoming requests, routes to appropriate method/handler Thin veneer behind API NOT a direct wrapper for components Converts request URL parts into arguments Usually handles call to representation service for responses MAY handle caching directives (skip for today) Advice for this event:- Keep it simple- Consider a very simple URL routing pattern (/{thing}/{id})- Use existing APIs (see listing today)
  77. 77. 77Let’s Build a Hypermedia Server!
  78. 78. 78Summary : Implementing Hypermedia Servers Components- Storage (DB, FileSys, external)- Object Model/Processing (objects, business rules) Connectors- Representation (convert object graph into media type)- Routing/Request Handling (convert URLs into args & route)
  79. 79. 79BUILDING HYPERMEDIACLIENTS
  80. 80. 80Building Hypermedia Clients Hypermedia clients for humans Hypermedia clients for machines
  81. 81. 81Hypermedia for Humans
  82. 82. 82What is a Hypermedia for Humans client?A client that is able todetermine possible protocol-level choices at runtimeusing only the links and forms in the message itself as a guide.
  83. 83. 83Some things to keep in mind…Hypermedia clients are based on the “Action Lifecycle”
  84. 84. 84Some things to keep in mind…http://en.wikipedia.org/wiki/Human_action_cycle
  85. 85. 85Some things to keep in mind…Oh!, I almost forgot…
  86. 86. 86Hypermedia clientsTypically hypermedia clients have almost no long-term memory.
  87. 87. 87Hypermedia clientsTypically hypermedia clients have almost no long-term memory.Hypermedia clients’ memories last for a single request/response cycle.
  88. 88. 88Hypermedia clientsTypically hypermedia clients have almost no long-term memory.Hypermedia clients’ memories last for a single request/response cycle.Clients MAY save a past response, parse it, store it, and recall it later.
  89. 89. 89Faithful Hypermedia Clients (FHCs) FHCs simply pass along whatever the server returns; usually to a human. FHCs MAY make some decisions on how to display the returned representation FHCs only need a starting URL and a (human) driver.
  90. 90. 90Guide for implementing an FHC Process the structure semantics in order to render view Process the protocol semantics in order to support available transitions Process the domain semantics in order to inform human of choices & results.
  91. 91. 91Process the structure semantics
  92. 92. 92Process the structure semantics
  93. 93. 93Process the structure semantics
  94. 94. 94Process protocol semantics
  95. 95. 95Process protocol semantics
  96. 96. 96Process protocol semantics
  97. 97. 97Process domain semantics
  98. 98. 98Process domain semantics
  99. 99. 99Summary for the Class Schedule FHC Structure Semantics- Take advantage of client-side XSLT- Build XSL processor for vnd.apiacademy-scheduling+xml- 120 lines of XSLT Protocol Semantics- Take advantage of XmlHttpRequest- Provide a single JS file that “understands” vnd.apiacademy-scheduling+xml- 130 lines of JS Domain Semantics- Use CSS to hide/show things for humans (.id, .dateCreated)- 130 lines of CSS
  100. 100. 100Advantages of hypermedia clients for humans Flexibility to support a wide range of non-breaking domain-level changes- Adding new display & input fields- Adding new resources/pages- Adding new link and form options (not new protocol options)- Changes in access control rules is “automatic” (No access? No controls!) Ability to separate “parsing” from “display”- Most hypermedia types keep clear separationbetween processing and display- Can make it easier to handle negotiationsbetween server devs and UI devs Ability to customize engines for devices- Same hypermedia message can be handleddifferently on each device, when applicable- Increased freedom for UI devs
  101. 101. 101Drawbacks of hypermedia clients for humans SoC can mean extra work for clients- Need to keep structure, protocol, domain clearly separated Possibility of changes in server can limit UI options- UI devs must plan for change (even before it happens) Anything short of FHC risks client adaptability- If client determines what to display, new fields will not appear.- If client determines what transitions to supportand in what order they appear, changes (add/move forms & links) may break the client. If the message format is unstable (breakingchanges occurring), FHCs have no realadvantage over one-off client coding.
  102. 102. 102Hypermedia for MachinesHypermedia for Machines
  103. 103. 103What is a hypermedia machine client?A client that is able toprocess responses,locate protocol actions, andmake domain-level choices at runtimeusing only the links and forms in the message itself as a guide.
  104. 104. 104What is a hypermedia machine client?A client that is able toprocess responses,locate protocol actions, andmake domain-level choices at runtimeusing only the links and forms in the message itself as a guide.
  105. 105. 105Agent Hypermedia Clients (AHCs) AHCs can process all three levels of messages:- Structure- Protocol- Domain AHCs MUST be able to make decisions on their own AHCs need only a starting URL http://xkcd.com/695/
  106. 106. 106Guide for implementing an AHC Process the structure semantics in order to know what’s “there” Process the protocol semantics in order to know what’s possible Process the domain semantics in order to make an informed choice The machine is in charge of the complete “Action Lifecycle”
  107. 107. 107Maze+XML Media Type
  108. 108. 108Maze+XML FHC
  109. 109. 109The Maze+XML AHC
  110. 110. 110“Teach” AHC about mazes
  111. 111. 111Process the structure semantics
  112. 112. 112Process the protocol semantics
  113. 113. 113Process the domain semantics
  114. 114. 114Summary for Maze+XML AHC Structure Semantics- XML DOM Parser + recognizing five elements (maze, collection, item,cell, link) Protocol Semantics- Support maze:link (H-factor=LO, HTTP.GET) Domain Semantics- Understand “wall-following” and choose between “start”, “north”, “south”, “east”,west”, and “exit” 150 lines of NodeJS code
  115. 115. 115Advantages of hypermedia clients for machines Ability to hand off tedious work to “smart” machine Using “generic” media types makes it possible to use the same client code forseveral different tasks/projects Coding new tasks gets faster over time since the baseline code already exists Simple modifications in the server (order to items in message) don’t break clients
  116. 116. 116Drawbacks of hypermedia clients for machines Making machines “smart” takes time, esp. for non-trivial tasks Some changes in message can break clients (missing transitions, new fields, etc.) Some unsafe operations (POST/PUT/DELETE) may need human interventionanyway. Not many “machine-friendly” hypermedia types yet.
  117. 117. 117Let’s Build a Hypermedia Client!
  118. 118. 118Summary : Building Hypermedia Clients Hypermedia clients for humans (FHC)- A client that is able to determine possible protocol-level choices at runtimeusing only the links and forms in the message itself as a guide. Hypermedia clients for machines (AHC)- A client that is able to process responses, locate protocol actions, and makedomain-level choices at runtime using only the links and forms in themessage itself as a guide. Hypermedia clients are based on the “Action Lifecycle” Hypermedia clients’ memories usually last for a single request/response cycle.
  119. 119. 119NOW WHAT?
  120. 120. 120Now What? Hypermedia goes back more than ½ a century Remember the H-Factors (LO, LE, LT, LI, LN, CR, CU, CM, CL) Always solve for the Three Pillars (Structure, Protocol, Domain) Servers have:- Components (Storage & Processing)- Connectors (Routing & Representation) Clients have:- No long-term memory- Support for Action Lifecycle- FHCs (for humans)- ACHs (for machines)
  121. 121. 121Let’s Grow the Hypermedia Web!
  122. 122. 122Available Server Projects YouTypeItWePostIt (:8080/api/)- https://github.com/mamund/rwa Maze+XML (:8181)- https://github.com/mamund/rwa Class-Schedule (:8282)- https://github.com/apiacademy/class-scheduling To-Do-REST (:8383)- https://github.com/mamund/to-do-rest
  123. 123. 123Designing and Implementing Hypermedia APIsQCon New York 2013 Mike Amundsen,Principal API ArchitectLayer 7 Techologies@mamund#HyperQCon

×