Upgrade to Pro — share decks privately, control downloads, hide ads and more …

What is Hypermedia API?

Marat
September 30, 2012

What is Hypermedia API?

Talk given on RubyShift 2012 in Kyiv September 29-30.

RoR did a great thing to make REST popular. Now it turns out that
original REST approach is not what we think REST is. But what it is
then? Hypermedia API is a new term which stands for original REST
approach. What is the difference between "REST" and Hypermedia API
(true REST)? What is Hypermedia? Why is it needed? These questions
are covered in my talk.

Marat

September 30, 2012
Tweet

Other Decks in Programming

Transcript

  1. What is Hypermedia API?

    View full-size slide

  2. client code <=> API code

    View full-size slide

  3. API:
    1. namespace
    2. its functions
    3. their params

    View full-size slide

  4. Web API:
    1. domain (https://graph.facebook.com/)
    2. addresses (/users, /groups, etc)
    3. params for them (?access_token=...&...)

    View full-size slide

  5. The main API problem:
    Client-server coupling

    View full-size slide

  6. Change in domain, URL, params →
    clients brake

    View full-size slide

  7. WWW exists 20 years.
    Clients don't brake

    View full-size slide

  8. You can upgrade at any time.

    View full-size slide

  9. Hypermedia API =
    Web API +
    Web experience

    View full-size slide

  10. Hypermedia API =
    1 URL
    https://api.github.com/
    https://api.twilio.com/2010-04-01

    View full-size slide

  11. Where are the URLs and params?

    View full-size slide

  12. MIME type description

    View full-size slide

  13. application/vnd.github-issue.text+json
    application/json
    application/vnd.tekpub.productions+json
    application/vnd.spire-io.session+json

    View full-size slide

  14. RFC2119:
    MUST, SHALL, REQUIRED
    SHOULD, RECOMMENDED
    MAY, OPTIONAL
    MUST NOT, SHALL NOT
    SHOULD NOT, NOT RECOMMENDED

    View full-size slide

  15. E.g.:
    Response representations MUST begin with
    element as the first element

    View full-size slide

  16. Servers SHOULD return a response code of
    204 if the HTTP DELETE request was
    successful.

    View full-size slide

  17. Document MAY contain a single filters object.
    Five properties: href(REQUIRED), rel
    (REQUIRED), name (OPTIONAL), prompt
    (OPTIONAL), and a data array (OPTIONAL)

    View full-size slide

  18. "filters":[
    {"rel":"category", "href":"...",
    "prompt":"",
    "data":[
    {"name":"category",
    "value":"Microsoft"}]},
    {"rel":"category", "href":"...",
    "prompt":"",
    "data":[{"name":"category",
    "value":"Ruby"}]}]

    View full-size slide

  19. "filters":[
    {"rel":"category", "href":"...",
    "prompt":"",
    "data":[
    {"name":"category",
    "value":"Microsoft"}]},
    {"rel":"category", "href":"...",
    "prompt":"",
    "data":[{"name":"category",
    "value":"Ruby"}]}]

    View full-size slide

  20. Rels are described in MIME

    View full-size slide

  21. Best MIME type is XHTML: it supports forms!

    View full-size slide

  22. 3 whales:
    HTTP + MIME + HATEOAS

    View full-size slide

  23. HATEOAS: hypermedia as the engine of
    application state

    View full-size slide


  24. q0
    uri = "..." />
    uri = "..." />


    q1
    uri = "..." />
    uri = "..." />

    View full-size slide

  25. ticket: {
    assigned_to: someone,
    links: [
    {rel: “unassign”, url: “...”},
    {rel: “close”, url: “...”}
    ]
    }

    View full-size slide

  26. ticket: {
    assigned_to: null,
    links: [
    {rel: “assign”, url: “...”},
    {rel: “remove”, url: “...”}
    ]
    }

    View full-size slide

  27. *MIME types are registered in IANA w/ public
    access

    View full-size slide

  28. HTTP verbs:
    GET
    HEAD
    POST
    PUT
    PATCH
    DELETE
    OPTIONS

    View full-size slide

  29. HTTP verbs:
    GET
    HEAD
    POST
    PUT
    PATCH
    DELETE
    OPTIONS

    View full-size slide

  30. Status codes:
    100.upto(505).almost_each do |status_code|

    end

    View full-size slide

  31. 100 Continue
    201 Created
    202 Accepted
    206 Partial Content
    303 See Other
    400 Bad Request
    401 Unauthorized
    404 Not Found
    409 Conflict
    412 Precondition Failed
    417 Expectation Failed

    View full-size slide

  32. 100 Continue
    201 Created
    202 Accepted
    206 Partial Content
    303 See Other
    400 Bad Request
    401 Unauthorized
    404 Not Found
    409 Conflict
    412 Precondition Failed
    417 Expectation Failed

    View full-size slide

  33. 100 Continue
    201 Created
    202 Accepted
    206 Partial Content
    303 See Other
    400 Bad Request
    401 Unauthorized
    404 Not Found
    409 Conflict
    412 Precondition Failed
    417 Expectation Failed

    View full-size slide

  34. 100 Continue
    201 Created
    202 Accepted
    206 Partial Content
    303 See Other
    400 Bad Request
    401 Unauthorized
    404 Not Found
    409 Conflict
    412 Precondition Failed
    417 Expectation Failed

    View full-size slide

  35. 100 Continue
    201 Created
    202 Accepted
    206 Partial Content
    303 See Other
    400 Bad Request
    401 Unauthorized
    404 Not Found
    409 Conflict
    412 Precondition Failed
    417 Expectation Failed

    View full-size slide

  36. 100 Continue
    201 Created
    202 Accepted
    206 Partial Content
    303 See Other
    400 Bad Request
    401 Unauthorized
    404 Not Found
    409 Conflict
    412 Precondition Failed
    417 Expectation Failed

    View full-size slide

  37. Request headers:
    OPTIONS /payment/order/1234
    HTTP 1.1
    Host: starbucks.example.com
    Response
    200 OK Allow: GET, PUT

    View full-size slide

  38. Request headers:
    PUT /order/1234 HTTP 1.1
    Host: starbucks.example.com
    Expect: 100-Continue
    Response:
    100 Continue

    View full-size slide

  39. Request:
    PUT /order/1234 HTTP 1.1
    Host: starbucks.example.com
    {body}
    Response:
    200 OK
    {body}

    View full-size slide

  40. Request:
    PUT /order/1234 HTTP 1.1
    Host: starbucks.example.com
    {body}
    Response:
    409 Conflict

    View full-size slide

  41. Request:
    PUT /order/1234 HTTP 1.1
    Host: starbucks.example.com
    Expect: 100-Continue
    Response:
    417 Expectation Failed

    View full-size slide

  42. HTTP Headers:
    Accept/type
    Etag
    Cache
    Authorization
    Version
    If-Unmodified-Since
    If-Match

    View full-size slide

  43. HTTP Headers:
    Accept/type
    Etag
    Cache
    Authorization
    Version
    If-Unmodified-Since
    If-Match

    View full-size slide

  44. Media types (revisited):
    Accept: application/xml
    Accept: application/json

    View full-size slide

  45. GET https://api.github.com/gists/1
    Accept: application/json
    200 OK
    Content-Type: application/json; charset=utf-8
    (response body)

    View full-size slide

  46. GET https://api.github.com/gists/1
    Accept: application/xml
    200 OK
    Content-Type: application/xml; charset=utf-8
    (response body)

    View full-size slide

  47. GET https://api.github.com/gists/1
    Accept: application/xml
    406 Not Acceptable
    Content-Type: application/json
    {
    "message": "Must ACCEPT application/json:
    [\"application/xml\"]"
    }

    View full-size slide

  48. HTTP Headers:
    Accept/type
    Etag
    Cache
    Authorization
    Version
    If-Unmodified-Since
    If-Match

    View full-size slide

  49. GET https://api.github.com/gists/1
    Accept: application/json
    200 OK
    ETag: "2259b5bea67655550030acf98bad4184"
    {body}
    GET https://api.github.com/gists/1
    Accept: application/json
    If-None-Match:
    "2259b5bea67655550030acf98bad4184"
    304 Not Modified

    View full-size slide

  50. HTTP Headers:
    Accept/type
    Etag
    Cache
    Authorization
    Version
    If-Unmodified-Since
    If-Match

    View full-size slide

  51. Authentication:
    Basic HTTP Authentication
    (with SSL or Digesting)

    View full-size slide

  52. HTTP Headers:
    Accept/type
    Etag
    Cache
    Authorization
    Version
    If-Unmodified-Since
    If-Match

    View full-size slide

  53. Accept: application/vnd.example+json
    Accept: application/vnd.example+json;version=1.0
    Accept: application/vnd.example-v2+json
    Start point URI remains: http://api.example.com

    View full-size slide

  54. HTTP Headers:
    Accept/type
    Etag
    Cache
    Authorization
    Version
    If-Unmodified-Since
    If-Match

    View full-size slide

  55. Richardson Maturity Model

    View full-size slide

  56. 1. “The Swamp of POX.” You’re using HTTP
    to make RPC calls. HTTP is only really used
    as a tunnel.
    http://api.example.com?post_id=1&user_id=2

    View full-size slide

  57. 2. Resources. Rather than making every call
    to a service endpoint, you have multiple
    endpoints.
    http://api.example.com/posts/edit/1
    http://api.example.com/users/show/1

    View full-size slide

  58. 3. HTTP Verbs.
    GET http://api.example.com/posts/1
    PUT http://api.example.com/posts/1
    PATCH http://api.example.com/posts/1
    POST http://api.example.com/posts
    DELETE http://api.example.com/posts/1

    View full-size slide

  59. 4. Hypermedia Controls. HATEOAS. You’re
    100% REST compliant.
    GET https://api.example.com/
    HTTP 1.1
    Accept: application/vnd.example-v1+json
    If-Match: “...”
    Authentication: ...
    200 OK
    {root: {entries: ...},
    links: [{rel: “edit”, url: “...”}, {…}]}

    View full-size slide

  60. No client-server coupling
    1 stable URL
    No dependencies on URLs and params

    View full-size slide

  61. Client is valid forever (ideally)

    View full-size slide

  62. Just as web browsers work

    View full-size slide

  63. Wish you all to be at level 4
    (if you want)

    View full-size slide

  64. “Architectural Styles and
    the Design of Network-based Software
    Architectures”
    http://www.ics.uci.edu/~fielding/pubs/di
    ssertation/top.htm

    View full-size slide

  65. http://blog.steveklabnik.com/posts/2012-02-
    27-hypermedia-api-reading-list

    View full-size slide

  66. “Building Hypermedia APIs with HTML5 and
    Node”
    Mike Amundsen

    View full-size slide

  67. http://timelessrepo.com/haters-gonna-hateoas

    View full-size slide

  68. REST is over!
    http://blog.steveklabnik.com/posts/2012-02-
    23-rest-is-over

    View full-size slide