Share
Embed
Slide 1
Slide 1 text
What is Hypermedia API?
Slide 2
Slide 2 text
client code <=> API code
Slide 3
Slide 3 text
API:
1. namespace
2. its functions
3. their params
Slide 4
Slide 4 text
Web API:
1. domain (https://graph.facebook.com/)
2. addresses (/users, /groups, etc)
3. params for them (?access_token=...&...)
Slide 5
Slide 5 text
The main API problem:
Client-server coupling
Slide 6
Slide 6 text
Change in domain, URL, params →
clients brake
Slide 7
Slide 7 text
No content
Slide 8
Slide 8 text
No content
Slide 9
Slide 9 text
WWW exists 20 years.
Clients don't brake
Slide 10
Slide 10 text
You can upgrade at any time.
Slide 11
Slide 11 text
No content
Slide 12
Slide 12 text
Hypermedia API =
Web API +
Web experience
Slide 13
Slide 13 text
Hypermedia API =
1 URL
https://api.github.com/
https://api.twilio.com/2010-04-01
Slide 14
Slide 14 text
Where are the URLs and params?
Slide 15
Slide 15 text
MIME type description
Slide 16
Slide 16 text
application/vnd.github-issue.text+json
application/json
application/vnd.tekpub.productions+json
application/vnd.spire-io.session+json
Slide 17
Slide 17 text
RFC2119:
MUST, SHALL, REQUIRED
SHOULD, RECOMMENDED
MAY, OPTIONAL
MUST NOT, SHALL NOT
SHOULD NOT, NOT RECOMMENDED
Slide 18
Slide 18 text
E.g.:
Response representations MUST begin with
element as the first element
Slide 19
Slide 19 text
Servers SHOULD return a response code of
204 if the HTTP DELETE request was
successful.
Slide 20
Slide 20 text
Document MAY contain a single filters object.
Five properties: href(REQUIRED), rel
(REQUIRED), name (OPTIONAL), prompt
(OPTIONAL), and a data array (OPTIONAL)
Slide 21
Slide 21 text
"filters":[
{"rel":"category", "href":"...",
"prompt":"",
"data":[
{"name":"category",
"value":"Microsoft"}]},
{"rel":"category", "href":"...",
"prompt":"",
"data":[{"name":"category",
"value":"Ruby"}]}]
Slide 22
Slide 22 text
"filters":[
{"rel":"category", "href":"...",
"prompt":"",
"data":[
{"name":"category",
"value":"Microsoft"}]},
{"rel":"category", "href":"...",
"prompt":"",
"data":[{"name":"category",
"value":"Ruby"}]}]
Slide 23
Slide 23 text
Rels are described in MIME
Slide 24
Slide 24 text
Best MIME type is XHTML: it supports forms!
Slide 25
Slide 25 text
No content
Slide 26
Slide 26 text
3 whales:
HTTP + MIME + HATEOAS
Slide 27
Slide 27 text
HATEOAS: hypermedia as the engine of
application state
Slide 28
Slide 28 text
No content
Slide 29
Slide 29 text
q0
q1
Slide 30
Slide 30 text
ticket: {
assigned_to: someone,
links: [
{rel: “unassign”, url: “...”},
{rel: “close”, url: “...”}
]
}
Slide 31
Slide 31 text
ticket: {
assigned_to: null,
links: [
{rel: “assign”, url: “...”},
{rel: “remove”, url: “...”}
]
}
Slide 32
Slide 32 text
*MIME types are registered in IANA w/ public
access
Slide 33
Slide 33 text
HTTP:
Slide 34
Slide 34 text
HTTP verbs:
GET
HEAD
POST
PUT
PATCH
DELETE
OPTIONS
Slide 35
Slide 35 text
HTTP verbs:
GET
HEAD
POST
PUT
PATCH
DELETE
OPTIONS
Slide 36
Slide 36 text
Status codes:
100.upto(505).almost_each do |status_code|
…
end
Slide 37
Slide 37 text
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
Slide 38
Slide 38 text
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
Slide 39
Slide 39 text
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
Slide 40
Slide 40 text
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
Slide 41
Slide 41 text
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
Slide 42
Slide 42 text
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
Slide 43
Slide 43 text
Request headers:
OPTIONS /payment/order/1234
HTTP 1.1
Host: starbucks.example.com
Response
200 OK Allow: GET, PUT
Slide 44
Slide 44 text
Request headers:
PUT /order/1234 HTTP 1.1
Host: starbucks.example.com
Expect: 100-Continue
Response:
100 Continue
Slide 45
Slide 45 text
Request:
PUT /order/1234 HTTP 1.1
Host: starbucks.example.com
{body}
Response:
200 OK
{body}
Slide 46
Slide 46 text
Request:
PUT /order/1234 HTTP 1.1
Host: starbucks.example.com
{body}
Response:
409 Conflict
Slide 47
Slide 47 text
Request:
PUT /order/1234 HTTP 1.1
Host: starbucks.example.com
Expect: 100-Continue
Response:
417 Expectation Failed
Slide 48
Slide 48 text
HTTP Headers:
Accept/type
Etag
Cache
Authorization
Version
If-Unmodified-Since
If-Match
Slide 49
Slide 49 text
HTTP Headers:
Accept/type
Etag
Cache
Authorization
Version
If-Unmodified-Since
If-Match
Slide 50
Slide 50 text
Media types (revisited):
Accept: application/xml
Accept: application/json
Slide 51
Slide 51 text
GET https://api.github.com/gists/1
Accept: application/json
200 OK
Content-Type: application/json; charset=utf-8
(response body)
Slide 52
Slide 52 text
GET https://api.github.com/gists/1
Accept: application/xml
200 OK
Content-Type: application/xml; charset=utf-8
(response body)
Slide 53
Slide 53 text
GET https://api.github.com/gists/1
Accept: application/xml
406 Not Acceptable
Content-Type: application/json
{
"message": "Must ACCEPT application/json:
[\"application/xml\"]"
}
Slide 54
Slide 54 text
HTTP Headers:
Accept/type
Etag
Cache
Authorization
Version
If-Unmodified-Since
If-Match
Slide 55
Slide 55 text
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
Slide 56
Slide 56 text
HTTP Headers:
Accept/type
Etag
Cache
Authorization
Version
If-Unmodified-Since
If-Match
Slide 57
Slide 57 text
Authentication:
Basic HTTP Authentication
(with SSL or Digesting)
Slide 58
Slide 58 text
HTTP Headers:
Accept/type
Etag
Cache
Authorization
Version
If-Unmodified-Since
If-Match
Slide 59
Slide 59 text
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
Slide 60
Slide 60 text
HTTP Headers:
Accept/type
Etag
Cache
Authorization
Version
If-Unmodified-Since
If-Match
Slide 61
Slide 61 text
Richardson Maturity Model
Slide 62
Slide 62 text
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
Slide 63
Slide 63 text
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
Slide 64
Slide 64 text
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
Slide 65
Slide 65 text
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: “...”}, {…}]}
Slide 66
Slide 66 text
No client-server coupling
1 stable URL
No dependencies on URLs and params
Slide 67
Slide 67 text
Client is valid forever (ideally)
Slide 68
Slide 68 text
Just as web browsers work
Slide 69
Slide 69 text
Wish you all to be at level 4
(if you want)
Slide 71
Slide 71 text
Sources:
Slide 72
Slide 72 text
“Architectural Styles and
the Design of Network-based Software
Architectures”
http://www.ics.uci.edu/~fielding/pubs/di
ssertation/top.htm
Slide 73
Slide 73 text
http://blog.steveklabnik.com/posts/2012-02-
27-hypermedia-api-reading-list
Slide 74
Slide 74 text
“Building Hypermedia APIs with HTML5 and
Node”
Mike Amundsen
Slide 75
Slide 75 text
http://timelessrepo.com/haters-gonna-hateoas
Slide 76
Slide 76 text
REST is over!
http://blog.steveklabnik.com/posts/2012-02-
23-rest-is-over
Slide 77
Slide 77 text
Questions!