0
What is Hypermedia API?
client code <=> API code
API:1. namespace2. its functions3. their params
Web API: 1. domain (https://graph.facebook.com/)    2. addresses (/users, /groups, etc)3. params for them (?access_token=....
The main API problem:Client-server coupling
Change in domain, URL, params →           clients brake
WWW exists 20 years. Clients dont brake
You can upgrade at any time.
Hypermedia API =   Web API + Web experience
Hypermedia API =               1 URL      https://api.github.com/https://api.twilio.com/2010-04-01
Where are the URLs and params?
MIME type description
application/vnd.github-issue.text+jsonapplication/jsonapplication/vnd.tekpub.productions+jsonapplication/vnd.spire-io.sess...
RFC2119:    MUST, SHALL, REQUIRED   SHOULD, RECOMMENDED        MAY, OPTIONAL     MUST NOT, SHALL NOTSHOULD NOT, NOT RECOMM...
E.g.:Response representations MUST begin with    <root> element as the first element
Servers SHOULD return a response code of  204 if the HTTP DELETE request was               successful.
Document MAY contain a single filters object.   Five properties: href(REQUIRED), rel (REQUIRED), name (OPTIONAL), prompt(O...
"filters":[    {"rel":"category", "href":"...","prompt":"",     "data":[       {"name":"category",        "value":"Microso...
"filters":[    {"rel":"category", "href":"...","prompt":"",     "data":[       {"name":"category",        "value":"Microso...
Rels are described in MIME
Best MIME type is XHTML: it supports forms!
3 whales:HTTP + MIME + HATEOAS
HATEOAS: hypermedia as the engine of         application state
<root>                <root> <id>q0</id>           <id>q1</id> <link rel = "q1"      <link rel = "q0"     uri = "..." />  ...
ticket: {  assigned_to: someone,  links: [    {rel: “unassign”, url: “...”},    {rel: “close”, url: “...”}  ]}
ticket: {  assigned_to: null,  links: [    {rel: “assign”, url: “...”},    {rel: “remove”, url: “...”}  ]}
*MIME types are registered in IANA w/ public                  access
HTTP:
HTTP verbs:    GET  HEAD   POST    PUT  PATCH DELETE OPTIONS
HTTP verbs:    GET  HEAD   POST    PUT  PATCH DELETE OPTIONS
Status codes:100.upto(505).almost_each do |status_code|…end
100 Continue      201 Created     202 Accepted  206 Partial Content     303 See Other   400 Bad Request   401 Unauthorized...
100 Continue      201 Created     202 Accepted  206 Partial Content     303 See Other   400 Bad Request   401 Unauthorized...
100 Continue      201 Created     202 Accepted  206 Partial Content     303 See Other   400 Bad Request   401 Unauthorized...
100 Continue      201 Created     202 Accepted  206 Partial Content     303 See Other   400 Bad Request   401 Unauthorized...
100 Continue      201 Created     202 Accepted  206 Partial Content     303 See Other   400 Bad Request   401 Unauthorized...
100 Continue      201 Created     202 Accepted  206 Partial Content     303 See Other   400 Bad Request   401 Unauthorized...
Request headers:OPTIONS /payment/order/1234HTTP 1.1Host: starbucks.example.comResponse200 OK Allow: GET, PUT
Request headers:PUT /order/1234 HTTP 1.1Host: starbucks.example.comExpect: 100-ContinueResponse:100 Continue
Request:PUT /order/1234 HTTP 1.1Host: starbucks.example.com{body}Response:200 OK{body}
Request:PUT /order/1234 HTTP 1.1Host: starbucks.example.com{body}Response:409 Conflict
Request:PUT /order/1234 HTTP 1.1Host: starbucks.example.comExpect: 100-ContinueResponse:417 Expectation Failed
HTTP Headers:Accept/typeEtagCacheAuthorizationVersionIf-Unmodified-SinceIf-Match
HTTP Headers:Accept/typeEtagCacheAuthorizationVersionIf-Unmodified-SinceIf-Match
Media types (revisited):Accept: application/xmlAccept: application/json
GET https://api.github.com/gists/1Accept: application/json200 OKContent-Type: application/json; charset=utf-8(response body)
GET https://api.github.com/gists/1Accept: application/xml200 OKContent-Type: application/xml; charset=utf-8(response body)
GET https://api.github.com/gists/1Accept: application/xml406 Not AcceptableContent-Type: application/json{"message": "Must...
HTTP Headers:Accept/typeEtagCacheAuthorizationVersionIf-Unmodified-SinceIf-Match
GET https://api.github.com/gists/1Accept: application/json200 OKETag: "2259b5bea67655550030acf98bad4184"{body}GET https://...
HTTP Headers:Accept/typeEtagCacheAuthorizationVersionIf-Unmodified-SinceIf-Match
Authentication:Basic HTTP Authentication (with SSL or Digesting)
HTTP Headers:Accept/typeEtagCacheAuthorizationVersionIf-Unmodified-SinceIf-Match
Accept: application/vnd.example+jsonAccept: application/vnd.example+json;version=1.0    Accept: application/vnd.example-v2...
HTTP Headers:Accept/typeEtagCacheAuthorizationVersionIf-Unmodified-SinceIf-Match
Richardson Maturity Model
1. “The Swamp of POX.” You’re using HTTPto make RPC calls. HTTP is only really used                 as a tunnel.http://api...
2. Resources. Rather than making every call   to a service endpoint, you have multiple                   endpoints.      h...
3. HTTP Verbs. GET http://api.example.com/posts/1 PUT http://api.example.com/posts/1PATCH http://api.example.com/posts/1 P...
4. Hypermedia Controls. HATEOAS. You’re         100% REST compliant.     GET https://api.example.com/                 HTTP...
No client-server coupling            1 stable URLNo dependencies on URLs and params
Client is valid forever (ideally)
Just as web browsers work
Wish you all to be at level 4       (if you want)
Thank you! @maratkamenmarat@svitla.com
Sources:
“Architectural Styles and  the Design of Network-based Software              Architectures”http://www.ics.uci.edu/~fieldin...
http://blog.steveklabnik.com/posts/2012-02-        27-hypermedia-api-reading-list
“Building Hypermedia APIs with HTML5 and                 Node”             Mike Amundsen
http://timelessrepo.com/haters-gonna-hateoas
REST is over!http://blog.steveklabnik.com/posts/2012-02-                23-rest-is-over
Questions!
Hypermedia API
Hypermedia API
Hypermedia API
Hypermedia API
Hypermedia API
Upcoming SlideShare
Loading in...5
×

Hypermedia API

3,699

Published on

Marat Kamenschykov presentation at Rubyshift 2012.

Published in: News & Politics
0 Comments
5 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
3,699
On Slideshare
0
From Embeds
0
Number of Embeds
6
Actions
Shares
0
Downloads
19
Comments
0
Likes
5
Embeds 0
No embeds

No notes for slide

Transcript of "Hypermedia API"

  1. 1. What is Hypermedia API?
  2. 2. client code <=> API code
  3. 3. API:1. namespace2. its functions3. their params
  4. 4. Web API: 1. domain (https://graph.facebook.com/) 2. addresses (/users, /groups, etc)3. params for them (?access_token=...&...)
  5. 5. The main API problem:Client-server coupling
  6. 6. Change in domain, URL, params → clients brake
  7. 7. WWW exists 20 years. Clients dont brake
  8. 8. You can upgrade at any time.
  9. 9. Hypermedia API = Web API + Web experience
  10. 10. Hypermedia API = 1 URL https://api.github.com/https://api.twilio.com/2010-04-01
  11. 11. Where are the URLs and params?
  12. 12. MIME type description
  13. 13. application/vnd.github-issue.text+jsonapplication/jsonapplication/vnd.tekpub.productions+jsonapplication/vnd.spire-io.session+json
  14. 14. RFC2119: MUST, SHALL, REQUIRED SHOULD, RECOMMENDED MAY, OPTIONAL MUST NOT, SHALL NOTSHOULD NOT, NOT RECOMMENDED
  15. 15. E.g.:Response representations MUST begin with <root> element as the first element
  16. 16. Servers SHOULD return a response code of 204 if the HTTP DELETE request was successful.
  17. 17. Document MAY contain a single filters object. Five properties: href(REQUIRED), rel (REQUIRED), name (OPTIONAL), prompt(OPTIONAL), and a data array (OPTIONAL)
  18. 18. "filters":[ {"rel":"category", "href":"...","prompt":"", "data":[ {"name":"category", "value":"Microsoft"}]}, {"rel":"category", "href":"...","prompt":"", "data":[{"name":"category", "value":"Ruby"}]}]
  19. 19. "filters":[ {"rel":"category", "href":"...","prompt":"", "data":[ {"name":"category", "value":"Microsoft"}]}, {"rel":"category", "href":"...","prompt":"", "data":[{"name":"category", "value":"Ruby"}]}]
  20. 20. Rels are described in MIME
  21. 21. Best MIME type is XHTML: it supports forms!
  22. 22. 3 whales:HTTP + MIME + HATEOAS
  23. 23. HATEOAS: hypermedia as the engine of application state
  24. 24. <root> <root> <id>q0</id> <id>q1</id> <link rel = "q1" <link rel = "q0" uri = "..." /> uri = "..." /> <link rel = "q2" <link rel = "q3" uri = "..." /> uri = "..." /></entry> </entry>
  25. 25. ticket: { assigned_to: someone, links: [ {rel: “unassign”, url: “...”}, {rel: “close”, url: “...”} ]}
  26. 26. ticket: { assigned_to: null, links: [ {rel: “assign”, url: “...”}, {rel: “remove”, url: “...”} ]}
  27. 27. *MIME types are registered in IANA w/ public access
  28. 28. HTTP:
  29. 29. HTTP verbs: GET HEAD POST PUT PATCH DELETE OPTIONS
  30. 30. HTTP verbs: GET HEAD POST PUT PATCH DELETE OPTIONS
  31. 31. Status codes:100.upto(505).almost_each do |status_code|…end
  32. 32. 100 Continue 201 Created 202 Accepted 206 Partial Content 303 See Other 400 Bad Request 401 Unauthorized 404 Not Found 409 Conflict412 Precondition Failed 417 Expectation Failed
  33. 33. 100 Continue 201 Created 202 Accepted 206 Partial Content 303 See Other 400 Bad Request 401 Unauthorized 404 Not Found 409 Conflict412 Precondition Failed 417 Expectation Failed
  34. 34. 100 Continue 201 Created 202 Accepted 206 Partial Content 303 See Other 400 Bad Request 401 Unauthorized 404 Not Found 409 Conflict412 Precondition Failed 417 Expectation Failed
  35. 35. 100 Continue 201 Created 202 Accepted 206 Partial Content 303 See Other 400 Bad Request 401 Unauthorized 404 Not Found 409 Conflict412 Precondition Failed 417 Expectation Failed
  36. 36. 100 Continue 201 Created 202 Accepted 206 Partial Content 303 See Other 400 Bad Request 401 Unauthorized 404 Not Found 409 Conflict412 Precondition Failed 417 Expectation Failed
  37. 37. 100 Continue 201 Created 202 Accepted 206 Partial Content 303 See Other 400 Bad Request 401 Unauthorized 404 Not Found 409 Conflict412 Precondition Failed 417 Expectation Failed
  38. 38. Request headers:OPTIONS /payment/order/1234HTTP 1.1Host: starbucks.example.comResponse200 OK Allow: GET, PUT
  39. 39. Request headers:PUT /order/1234 HTTP 1.1Host: starbucks.example.comExpect: 100-ContinueResponse:100 Continue
  40. 40. Request:PUT /order/1234 HTTP 1.1Host: starbucks.example.com{body}Response:200 OK{body}
  41. 41. Request:PUT /order/1234 HTTP 1.1Host: starbucks.example.com{body}Response:409 Conflict
  42. 42. Request:PUT /order/1234 HTTP 1.1Host: starbucks.example.comExpect: 100-ContinueResponse:417 Expectation Failed
  43. 43. HTTP Headers:Accept/typeEtagCacheAuthorizationVersionIf-Unmodified-SinceIf-Match
  44. 44. HTTP Headers:Accept/typeEtagCacheAuthorizationVersionIf-Unmodified-SinceIf-Match
  45. 45. Media types (revisited):Accept: application/xmlAccept: application/json
  46. 46. GET https://api.github.com/gists/1Accept: application/json200 OKContent-Type: application/json; charset=utf-8(response body)
  47. 47. GET https://api.github.com/gists/1Accept: application/xml200 OKContent-Type: application/xml; charset=utf-8(response body)
  48. 48. GET https://api.github.com/gists/1Accept: application/xml406 Not AcceptableContent-Type: application/json{"message": "Must ACCEPT application/json:["application/xml"]"}
  49. 49. HTTP Headers:Accept/typeEtagCacheAuthorizationVersionIf-Unmodified-SinceIf-Match
  50. 50. GET https://api.github.com/gists/1Accept: application/json200 OKETag: "2259b5bea67655550030acf98bad4184"{body}GET https://api.github.com/gists/1Accept: application/jsonIf-None-Match:"2259b5bea67655550030acf98bad4184"304 Not Modified
  51. 51. HTTP Headers:Accept/typeEtagCacheAuthorizationVersionIf-Unmodified-SinceIf-Match
  52. 52. Authentication:Basic HTTP Authentication (with SSL or Digesting)
  53. 53. HTTP Headers:Accept/typeEtagCacheAuthorizationVersionIf-Unmodified-SinceIf-Match
  54. 54. Accept: application/vnd.example+jsonAccept: application/vnd.example+json;version=1.0 Accept: application/vnd.example-v2+json Start point URI remains: http://api.example.com
  55. 55. HTTP Headers:Accept/typeEtagCacheAuthorizationVersionIf-Unmodified-SinceIf-Match
  56. 56. Richardson Maturity Model
  57. 57. 1. “The Swamp of POX.” You’re using HTTPto make RPC calls. HTTP is only really used as a tunnel.http://api.example.com?post_id=1&user_id=2
  58. 58. 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
  59. 59. 3. HTTP Verbs. GET http://api.example.com/posts/1 PUT http://api.example.com/posts/1PATCH http://api.example.com/posts/1 POST http://api.example.com/postsDELETE http://api.example.com/posts/1
  60. 60. 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: “...”}, {…}]}
  61. 61. No client-server coupling 1 stable URLNo dependencies on URLs and params
  62. 62. Client is valid forever (ideally)
  63. 63. Just as web browsers work
  64. 64. Wish you all to be at level 4 (if you want)
  65. 65. Thank you! @maratkamenmarat@svitla.com
  66. 66. Sources:
  67. 67. “Architectural Styles and the Design of Network-based Software Architectures”http://www.ics.uci.edu/~fielding/pubs/di ssertation/top.htm
  68. 68. http://blog.steveklabnik.com/posts/2012-02- 27-hypermedia-api-reading-list
  69. 69. “Building Hypermedia APIs with HTML5 and Node” Mike Amundsen
  70. 70. http://timelessrepo.com/haters-gonna-hateoas
  71. 71. REST is over!http://blog.steveklabnik.com/posts/2012-02- 23-rest-is-over
  72. 72. Questions!
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×