Exist In the Web - Not on it

Exist In the Web - Not on it

A 30,000 ft view on how we can model our public web APIs close to how HTTP was designed to be used, and an illustration of what kinds of problems hypermedia web api can try and solve for your in your public web API.

B83d5b590577969ee79a5ad845411a7d?s=128

Amy Palamountain

July 25, 2013
Tweet

Transcript

  1. E WEB IN THE NOT JUST ON IT IN GREAT

    APIS
  2. @ammeep note: may not be a shark horse in real

    life
  3. apis ’ suck

  4. that’s not R

  5. that’s notH p

  6. ACCESSIBLE Gourmet Apis

  7. Premium APIs CONSISTENCY teed an

  8. DESCRIPTIVE E for the premium user

  9. HEAVY DUTY For apis that stand the test of time

    F b APIS
  10. the web go with the grain of

  11. SOAP APIS

  12. CENTRIC DESIGN ACTION

  13. wsdl/"targetNamespace="http://ws.c <wsdl:types> <s:schema elementFormDefault="qua <s:element name="GetWeatherInfor <s:complexType/> </s:element> <s:element name="GetWeatherInfor

    <s:complexType> <s:sequence> <s:element minOccurs="0" maxOc name="GetWeatherInformation type="tns:ArrayOfWeatherDes </s:complexType>
  14. 100% b

  15. Super F b

  16. None
  17. H T TP doesn't leverage

  18. THE BODY CRAM EVERY} } STUFF pack THING possiblE IN

  19. codes Error In the body > <

  20. e o C Sis t t n $.ajax({ url: '/music/catalog',

    success: function(){ // Parse the body and check for errors! }, error: function(){ // An error code would have been nice! } });
  21. SOAP & RPC for public APIs Is not a good

    fit
  22. not on it in the web EXIST

  23. R r

  24. defined by a uri Resources api.com/thing

  25. defined by a uri Resources api.com/thing/123

  26. HOW to resources? do we do stuff

  27. resources interact with via http verbs } }

  28. HOW? VERB => NOUN

  29. HOW? VERB => URI

  30. GET POST PUT DELETE L b /music/album

  31. GET POST PUT DELETE G b /music/album/123

  32. GET POST PUT DELETE b /music/album

  33. GET POST PUT DELETE E b /music/album/123

  34. GET POST PUT DELETE Cr & N /music/song/epic.mp3

  35. GET POST PUT DELETE N p w .../song/epic.mp3

  36. OPTIONS HEAD PATCH COPY LINK UNLINK PURGE O r

  37. status Im 200 ok - honest codes

  38. ENOUGH FOR HEADERS GENERIC

  39. 1XX 3XX 4XX 2XX 5XX SEND MORE NOW!

  40. 1XX 3XX 4XX 2XX 5XX \o/ 1XX

  41. 1XX 3XX 4XX 2XX 5XX 1XX These guys? they moved

  42. 1XX 3XX 4XX 2XX 5XX 1XX I have no idea

    what you just said
  43. 1XX 3XX 4XX 2XX 5XX 1XX The server is exploding

  44. P P Use THEM

  45. r p

  46. am azing ap i's DOMAIN concepts expose

  47. ACCESSIBLE Gourmet Apis

  48. Premium APIs CONSISTENCY teed an

  49. CAN WE GO FURTHER ?

  50. ALL /music/album LISTEN /music/album/123 BUY /music/album/123 /song/epic.mp3 UPLOAD DELETE /song/epic.mp3

  51. M r R r manipulated via Http verbs

  52. ? How the do we use this api HECK

  53. READ THE DOCS

  54. THEN BAKE IT IN

  55. what if the relationships between resources changes w

  56. REDEPLOY ALL THE CLIENTS

  57. How does the internet work?

  58. REDEPLOY ALL THE CLIENTS BROWSERS

  59. JUST CHANGE THE SERVER

  60. HTTP GET ACCEPT : /catalog : text/html VIEW ALBUMS ABBA

    Their ‘gift’ to the world can be still be found today, in karaoke bars world wide. MEAT LOAF Meat Loaf’s father was an alcoholic who would go on drinking binges for days at a time. VIEW ALBUMS VIEW ALBUMS DAVID BOWIE He challenged the core belief of the rock music of its day & created perhaps the biggest cult in popular culture. THE PIXIES An unorthodox marriage of surf music and punk rock. Some of the most compelling music of the 80s VIEW ALBUMS http://musicstore.com/catalog
  61. PRE ORDER “Heroes” The twelfth studio album by David Bowie,

    released in 1977. The second instalment of his Berlin Trilogy. Ziggy Stardust & the Spiders from Mars Aladdin Sane Riding the wave of Ziggy Stardust, there's a wealth of classic material here, but not enough focus to make this album itself a classic. A rock star acts as a messenger for extraterrestrial beings BUY ALBUM http://musicstore.com/albums/bowie Young Americans David recorded the music for this album first. Mid session he would stop, write an idea down. He wrote the lyrics only after the music was recorded BUY ALBUM HTTP GET ACCEPT : /albums/bowie : text/html BUY ALBUM
  62. BUY ALBUM “Heroes” The twelfth studio album by David Bowie,

    released in 1977. The second instalment of his Berlin Trilogy. Ziggy Stardust & the Spiders from Mars Aladdin Sane Riding the wave of Ziggy Stardust, there's a wealth of classic material here, but not enough focus to make this album itself a classic. A rock star acts as a messenger for extraterrestrial beings BUY ALBUM http://musicstore.com/albums/bowie Young Americans David recorded the music for this album first. Mid session he would stop, write an idea down. He wrote the lyrics only after the music was recorded BUY ALBUM BUY ALBUM HTTP GET ACCEPT : /albums/bowie : text/html
  63. HTTP POST ACCEPT : /checkout : text/html Checkout “Heroes” The

    twelfth studio album by David Bowie, released in 1977. The second instalment of his Berlin Trilogy. http://musicstore.com/checkout Total: $10.00 You are purchasing... Name on card Credit Card # Verification Code
  64. LISTEN “Heroes” The twelfth studio album by David Bowie, released

    in 1977. The second instalment of his Berlin Trilogy. Ziggy Stardust & the Spiders from Mars Aladdin Sane Riding the wave of Ziggy Stardust, there's a wealth of classic material here, but not enough focus to make this album itself a classic. A rock star acts as a messenger for extraterrestrial beings BUY ALBUM http://musicstore.com/albums/bowie Young Americans David recorded the music for this album first. Mid session he would stop, write an idea down. He wrote the lyrics only after the music was recorded BUY ALBUM BUY ALBUM HTTP GET ACCEPT : /albums/bowie : text/html
  65. link to documents actions POSSIBLE HTML

  66. The client is the v r

  67. CAN WE DO THIS WITH APIS

  68. Hypermedia

  69. think LINKS

  70. <link rel="catalog" title="Catalog" href="/music/catalog" /> HTML LINKS

  71. JSON LINKS "link": { "rel":"catalog", "title":"Catalog", "href":"/music/catalog" } HTML LINKS

    <link rel="catalog" title="Catalog" href="/music/catalog" />
  72. XML LINKS HTML LINKS <link rel="catalog" title="Catalog" href="/music/catalog" /> <link>

    <rel> catalog </rel> <title> Catalog </title> <href> /music/catalog </href> </link>
  73. LOL LINKS HTML LINKS <link rel="catalog" title="Catalog" href="/music/catalog" />

  74. HTML JSON XML HAL S r f r

  75. HTML JSON XML HAL M T

  76. HTTP GET ACCEPT : /catalog : application/xml <catalog> <artist> <name>David

    Bowie</name> <description>.....</description> <links> <link> <rel> Albums </rel> <title> List Albums </title> <href> /albums/bowie </href> </link> ...... </links> </artist> ....... </catalog>
  77. <albums> <album> <name>Aladdin Sane</name> <description>.....</description> <links> <link> <rel> Purchase </rel>

    <title>Buy Now</title> <href> /checkout </href> </link> <link> <rel> Album Preview </rel> <title>Preview Tracks</title> <href> /albums/bowie/aladdinsane/preview </href> </link> ...... </links> </album> HTTP GET ACCEPT : /albums/bowie : application/xml
  78. <albums> <album> <name>Aladdin Sane</name> <description>.....</description> <links> <link> <rel> Stream </rel>

    <title>Listen</title> <href> /albums/bowie/aladdinsane/listen</href> </link> <link> <rel> Related Artists </rel> <title>Other Albums You Might Like</title> <href> /albums/similar/bowie</href> </link> ...... </links> </album> HTTP GET ACCEPT : /albums/bowie : application/xml
  79. no out of band f r

  80. show how resources & actions are related

  81. to interact with the problem space show how

  82. changes within the problem space enable

  83. Look Mum No hands

  84. Look Mum No hands KINDA

  85. HYPERMEDIA APIS NEED HYPERMEDIA CLIENTS

  86. A LINK W

  87. r representation

  88. generic clients interpret representations rpr <Generic Clients> {representations}

  89. ACtion Specific APIS

  90. ACtion Specific APIS Resource Driven APis

  91. ACtion Specific APIS Hypermedia Driven APIS Resource Driven APis

  92. EVOLV ABLE Generic CLIENTS ACtion Specific Clients

  93. WHY LINK

  94. OVERHEAD R OF UPDATES

  95. DISCOVERABILITY R is a big deal for you

  96. HYPERMEDIA DRIVEN APIs Resource Oriented APIS

  97. Hypermedia even if you choose not to use it. DESIGN

    for
  98. As API providers, our E1 Priority is building apis that

    don't suck
  99. ACCESSIBLE Gourmet Apis

  100. Premium APIs CONSISTENCY teed an

  101. DESCRIPTIVE E for the premium user

  102. HEAVY DUTY For apis that stand the test of time

    F b APIS
  103. BUILD APIS IN THE WEB

  104. Thank you! @ammeep amy.palamounta.in internet related activities: greenbutton.com google: hypermedia

    apis bizcoder.com stateless.co/hal_specification.html @alliebrosh for the hyperboleandahalf character