$30 off During Our Annual Pro Sale. View Details »

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.

Amy Palamountain

July 25, 2013
Tweet

More Decks by Amy Palamountain

Other Decks in Programming

Transcript

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

    View Slide

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

    View Slide

  3. apis

    suck

    View Slide

  4. that’s not R

    View Slide

  5. that’s notH p

    View Slide

  6. ACCESSIBLE
    Gourmet
    Apis

    View Slide

  7. Premium APIs
    CONSISTENCY
    teed
    an

    View Slide

  8. DESCRIPTIVE
    E
    for the premium user

    View Slide

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

    View Slide

  10. the web
    go with the grain of

    View Slide

  11. SOAP
    APIS

    View Slide

  12. CENTRIC DESIGN
    ACTION

    View Slide

  13. wsdl/"targetNamespace="http://ws.c



    name="GetWeatherInformation
    type="tns:ArrayOfWeatherDes

    View Slide

  14. 100%
    b

    View Slide

  15. Super
    F b

    View Slide

  16. View Slide

  17. H T TP
    doesn't
    leverage

    View Slide

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

    View Slide

  19. codes
    Error
    In the body
    > <

    View Slide

  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!
    }
    });

    View Slide

  21. SOAP & RPC
    for public APIs
    Is not a good fit

    View Slide

  22. not on it
    in the web
    EXIST

    View Slide

  23. R r

    View Slide

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

    View Slide

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

    View Slide

  26. HOW
    to resources?
    do we do stuff

    View Slide

  27. resources
    interact with
    via http verbs
    }
    }

    View Slide

  28. HOW?
    VERB => NOUN

    View Slide

  29. HOW?
    VERB => URI

    View Slide

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

    View Slide

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

    View Slide

  32. GET
    POST
    PUT
    DELETE
    b
    /music/album

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  36. OPTIONS
    HEAD
    PATCH
    COPY
    LINK
    UNLINK
    PURGE
    O r

    View Slide

  37. status
    Im 200 ok - honest
    codes

    View Slide

  38. ENOUGH
    FOR HEADERS
    GENERIC

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

  42. 1XX
    3XX
    4XX
    2XX
    5XX
    1XX
    I have no
    idea what
    you just
    said

    View Slide

  43. 1XX
    3XX
    4XX
    2XX
    5XX
    1XX
    The
    server is
    exploding

    View Slide

  44. P
    P
    Use THEM

    View Slide

  45. r p

    View Slide

  46. am
    azing ap
    i's
    DOMAIN
    concepts
    expose

    View Slide

  47. ACCESSIBLE
    Gourmet
    Apis

    View Slide

  48. Premium APIs
    CONSISTENCY
    teed
    an

    View Slide

  49. CAN WE GO
    FURTHER
    ?

    View Slide

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

    View Slide

  51. M r R r
    manipulated
    via Http verbs

    View Slide

  52. ?
    How the
    do we use this api
    HECK

    View Slide

  53. READ THE DOCS

    View Slide

  54. THEN BAKE IT IN

    View Slide

  55. what if the relationships
    between resources changes
    w

    View Slide

  56. REDEPLOY ALL THE CLIENTS

    View Slide

  57. How does the
    internet work?

    View Slide

  58. REDEPLOY ALL THE CLIENTS
    BROWSERS

    View Slide

  59. JUST CHANGE THE SERVER

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  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

    View Slide

  65. link to
    documents
    actions
    POSSIBLE
    HTML

    View Slide

  66. The client is the
    v r

    View Slide

  67. CAN WE DO THIS WITH APIS

    View Slide

  68. Hypermedia

    View Slide

  69. think
    LINKS

    View Slide


  70. HTML LINKS

    View Slide

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

    View Slide

  72. XML LINKS
    HTML LINKS


    catalog
    Catalog
    /music/catalog

    View Slide

  73. LOL LINKS
    HTML LINKS

    View Slide

  74. HTML
    JSON
    XML
    HAL S r f r

    View Slide

  75. HTML
    JSON
    XML
    HAL
    M
    T

    View Slide

  76. HTTP GET
    ACCEPT
    : /catalog
    : application/xml


    David Bowie
    .....


    Albums
    List Albums
    /albums/bowie

    ......


    .......

    View Slide



  77. Aladdin Sane
    .....


    Purchase
    Buy Now
    /checkout


    Album Preview
    Preview Tracks
    /albums/bowie/aladdinsane/preview

    ......


    HTTP GET
    ACCEPT
    : /albums/bowie
    : application/xml

    View Slide



  78. Aladdin Sane
    .....


    Stream
    Listen
    /albums/bowie/aladdinsane/listen


    Related Artists
    Other Albums You Might Like
    /albums/similar/bowie

    ......


    HTTP GET
    ACCEPT
    : /albums/bowie
    : application/xml

    View Slide

  79. no out of band
    f r

    View Slide

  80. show how
    resources & actions are related

    View Slide

  81. to interact with the problem space
    show how

    View Slide

  82. changes within the problem space
    enable

    View Slide

  83. Look Mum
    No hands

    View Slide

  84. Look Mum
    No hands
    KINDA

    View Slide

  85. HYPERMEDIA
    APIS
    NEED
    HYPERMEDIA
    CLIENTS

    View Slide

  86. A LINK
    W

    View Slide

  87. r
    representation

    View Slide

  88. generic clients
    interpret
    representations
    rpr

    {representations}

    View Slide

  89. ACtion
    Specific
    APIS

    View Slide

  90. ACtion
    Specific
    APIS
    Resource
    Driven APis

    View Slide

  91. ACtion
    Specific
    APIS
    Hypermedia
    Driven
    APIS
    Resource
    Driven APis

    View Slide

  92. EVOLV
    ABLE
    Generic
    CLIENTS
    ACtion
    Specific
    Clients

    View Slide

  93. WHY LINK

    View Slide

  94. OVERHEAD
    R
    OF UPDATES

    View Slide

  95. DISCOVERABILITY
    R
    is a big deal for you

    View Slide

  96. HYPERMEDIA
    DRIVEN APIs
    Resource
    Oriented
    APIS

    View Slide

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

    View Slide

  98. As API providers, our
    E1
    Priority is building apis
    that don't suck

    View Slide

  99. ACCESSIBLE
    Gourmet
    Apis

    View Slide

  100. Premium APIs
    CONSISTENCY
    teed
    an

    View Slide

  101. DESCRIPTIVE
    E
    for the premium user

    View Slide

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

    View Slide

  103. BUILD APIS
    IN THE WEB

    View Slide

  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

    View Slide