Implementing Hypermedia Clients: It's Not Rocket Science – Mike Amundsen, Principal API Architect, Layer 7

3,667 views

Published on

Coding hypermedia clients need not be ugly nor complicated. This session shows you how to write clean, adaptive code that responds to changes in data and workflow requirements over time. This session covers the truth (both good and bad) about hypermedia client coding and includes examples of several client models that handle evolvable Hypermedia APIs without sacrificing user experience or requiring Herculean effort on the part of developers.

Published in: Technology

Implementing Hypermedia Clients: It's Not Rocket Science – Mike Amundsen, Principal API Architect, Layer 7

  1. 1. 1Implementing Hypermedia Clients:It’s Not Rocket Science Mike Amundsen,Principal API ArchitectLayer 7 Technologies@mamund
  2. 2. 2Mike Amundsen Author, Web Architect, Presenter Principal API Architect “Help people build great APIs for the Web.” Part of the API Academy
  3. 3. 3API Academy Team
  4. 4. 4Mike Amundsen Building Hypermedia APIs with HTML5 and Node (2011) Focus on hypermedia theory and practice Examples for both humans and M2M scenarios Guidance on designing and registering media types
  5. 5. 5Mike Amundsen RESTful Web APIs w/ Leonard Richardson and Sam Ruby (August 2013) Good for both introduction and in-depth REST skills Emphasis on protocol-level hypermedia Focus on closing the app-level semantic gap Guidance on creating machine-readable documentation Sample Galley proof at the O’Reilly booth this week.
  6. 6. 6Mike Amundsen Office Hours in the Exhibit Hall- Today – right after this session Book signing at the O’Reilly Booth- Today at 5:45P Available here throughout the week – come up and say ‘Hi!’ @mamund on Twitter
  7. 7. 7It may be hard work, but it’s notRocket Science.
  8. 8. 8HYPERMEDIA: A SHORT HISTORY
  9. 9. 9Vannevar Bush“As We May Think”, July 1945“Consider a future device for individual use, which is a sortof mechanized private file and library. It needs a name, andto coin one at random, "memex" will do.”
  10. 10. 10Douglas Engelbart“Augmenting Human Intelligence”, 1962oNLineSystem (NLS), 1968Inventor of the “mouse”“We refer to a way of life in an integrateddomain where hunches, cut-and-try,intangibles, and the human "feel for asituation" usefully co-exist with powerfulconcepts, streamlined terminology andnotation, sophisticated methods, and high-powered electronic aids.”
  11. 11. 11Theodor Nelson“Computer Lib/Dream Machines”, 1974Coined “hypertext”Father of the “Cyber-culture”“ If computers are the wave of the future, displays are thesurfboards.”
  12. 12. 12Roy T. Fielding“Architectural Styles and the Design of Network-basedSoftware Architectures”, 2000Identified REST architectural style"Hypermedia is defined by the presence of applicationcontrol information embedded within, or as a layer above,the presentation of information. Distributed hypermediaallows the presentation and control information to be storedat remote locations."
  13. 13. 13Roy T. Fielding“Hypermedia is defined by the presence ofapplication control information embeddedwithin, or as a layer above, the presentationof information."
  14. 14. 14Roy T. Fielding“Hypermedia is defined by the presence ofapplication control information embeddedwithin, or as a layer above, the presentationof information."
  15. 15. 15Roy T. Fielding“Hypermedia is defined by the presence ofapplication control information embeddedwithin, or as a layer above, the presentationof information."
  16. 16. 16HYPERMEDIA ANATOMY
  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 pre-defined collection of H-Factors is called a “Media Type” Each media type has it’s own “H-Factor” signature.
  33. 33. 33A HYPERMEDIA TYPE
  34. 34. 34On the Web, media types don’t define a solution,they describe a problem domain
  35. 35. 35The more descriptive the media type,the easier it is to talk about the problem
  36. 36. 36What problem domain is described byPlain Text?CSV?XML?JSON?YAML?Atom?HTML?VoiceXML?
  37. 37. 37Let’s describe the Class Scheduling domain…
  38. 38. 38Let’s describe the Class Scheduling domain…and let’s keep it real simple today.
  39. 39. 39application/vnd.apiacademy-scheduling+xml
  40. 40. 40Domain 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
  41. 41. 41Let’s map the actions to (at least) one Web protocol…
  42. 42. 42Let’s map the actions to (at least) one Web protocol…We could use HTTP, WebSockets, XMPP…
  43. 43. 43Let’s map the actions to (at least) one Web protocol…We could use HTTP, WebSockets, XMPP…But, of course, we’ll use HTTP today.
  44. 44. 44Protocol Map eight actions:- add, update, remove,read, list, filter,assign, unassign To four HTTP methods:- GET, POST,PUT, DELETE.
  45. 45. 45Let’s document the possible data elementsfor each action, too.
  46. 46. 46Data elements with actions…
  47. 47. 47Finally, let’s design a single messagethat can carry all that information…
  48. 48. 48Structure 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
  49. 49. 49Note there are three key aspects to each message design…
  50. 50. 50Three Semantic Layers for a Media Type 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.
  51. 51. 51Now let’s see some examples…
  52. 52. 52
  53. 53. 53And magically a server appears….(we’ll cover server implementation some other time).
  54. 54. 54Sample response from a compliant server
  55. 55. 55HYPERMEDIA FOR HUMANS
  56. 56. 56What 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.
  57. 57. 61Some things to keep in mind…Hypermedia clients are based on the “Action Lifecycle”
  58. 58. 62Some things to keep in mind…http://en.wikipedia.org/wiki/Human_action_cycle
  59. 59. 63Some things to keep in mind…Oh!, I almost forgot…
  60. 60. 64Hypermedia clientsTypically hypermedia clients have almost no long-term memory.
  61. 61. 65Hypermedia clientsTypically hypermedia clients have almost no long-term memory.Hypermedia clients’ memories last for a single request/response cycle.
  62. 62. 66Hypermedia 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.
  63. 63. 67Faithful 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.
  64. 64. 68Guide 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.
  65. 65. 69Process the structure semantics
  66. 66. 70Process the structure semantics
  67. 67. 71Process the structure semantics
  68. 68. 72Process protocol semantics
  69. 69. 73Process protocol semantics
  70. 70. 74Process protocol semantics
  71. 71. 75Process domain semantics
  72. 72. 76Process domain semantics
  73. 73. 77Summary 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
  74. 74. 78Advantages 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 separation between 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
  75. 75. 79Drawbacks 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.
  76. 76. 80HYPERMEDIA FOR MACHINES
  77. 77. 81What 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.
  78. 78. 82Agent 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/
  79. 79. 83Guide 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”
  80. 80. 84Maze+XML Media Type
  81. 81. 85Maze+XML FHC
  82. 82. 86The Maze+XML AHC
  83. 83. 87“Teach” AHC about mazes
  84. 84. 88Process the structure semantics
  85. 85. 89Process the protocol semantics
  86. 86. 90Process the domain semantics
  87. 87. 91Summary 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
  88. 88. 92Advantages 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
  89. 89. 93Drawbacks 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.
  90. 90. 94SUMMARY
  91. 91. 95HistoryHypermedia was there from “day one” but many times we still don’t use iton the Web.
  92. 92. 96AnatomyH-Factors give us a way to look at hypermedia separately and designmessages according to our needs.
  93. 93. 97InteractionBuilding hypermedia clients means relying on Norman’s “Action Lifecycle”
  94. 94. 98ImplementationWeb clients must always be able to handle three type of semantics:Structure, Protocol, Domain
  95. 95. 99Hypermedia for HumansFHCs (faithful renders) add flexibility for future non-breaking changes bysacrificing some freedom in the initial design (plan for the “unexpected”)
  96. 96. 100Hypermedia for MachinesAHCs (agents) make it possible to use a “generic” format tohandle tedious tasks as long as the machine can be“smart enough” for the domain.
  97. 97. 101Remember…
  98. 98. 102It may be hard work, but it’s notRocket Science.Thank you!
  99. 99. 103Implementing Hypermedia Clients:It’s Not Rocket Science Mike Amundsen,Principal API ArchitectLayer 7 Technologies@mamund

×