Designing Hypermedia APIs

Designing
Hypermedia
APIs
@steveklabnik
Sunday, November 18, 12

View Slide


View Slide

“People are fairly good at short-term
design, and usually awful at long-term
design. Most don’t think they need to
design past the current release.”
Problem

View Slide

Solution?

View Slide

Solution
Flexibility
Stability

View Slide

“But what distinguishes the worst
architect from the best of bees is this, that
the architect raises his structure in
imagination before he erects it in reality.”
Karl Marx

View Slide

GET / HTTP/1.1
Host: www.example.com
HTTP/1.1 200 OK
Content-Length: 438
Content-Type: application/json
Link: ; rel="profile"
{
"statuses":[
{
"body":"neato",
"username":"steveklabnik"
},
{
"body":"testing testing",
}
],
"template":{
"body":"",
"username":""
},
"links":[
{
"rel":"collection",
"href":"/"
}
]
}

View Slide

GET / HTTP/1.1
HTTP/1.1 200 OK
Content-Length: 438
{
"statuses":[
{
"body":"neato",
},
{
}
],
"template":{
"body":"",
"username":""
},
"links":[
{
"rel":"collection",
"href":"/statuses"
}
]
}

View Slide

POST / HTTP/1.1
{
"body":"hello, hypermedia",
}
HTTP/1.1 201 Created
Content-Length: 438
Location: "/"
{"message":"you are being redirected"}

View Slide

GET / HTTP/1.1
HTTP/1.1 200 OK
Content-Length: 438
{
"statuses":[
{
"body":"neato",
},
{
},
{
},
],
"template":{
"body":"",
"username":""
},
"links":[
{
"rel":"collection",
"href":"/"
}
]}

View Slide

Adapters

View Slide

Coupling - Demeter
class Foo
def initialize(bar)
@bar = bar
end
def process
@bar.qux.fetch_data
end
end

View Slide

Coupling - Demeter
describe Foo do
it “fetches data” do
bar = Bar.new
bar.stub(:qux =>
stub(:fetch_data => “data”)
)
expect(Foo.new(bar).process).to eq(“data”)
end
end

View Slide

Coupling - Demeter
Demeter is actually
about types.
@bar.qux.fetch_data

View Slide

Coupling - Demeter
You can tell something is
coupled because it breaks
when you change it.

View Slide

Coupling - Demeter
Stability: doesn’t break over time
Flexibility: ability to change

View Slide

Solution
Radical
decoupling

View Slide


View Slide

Decoupling

View Slide

Decoupling
GET / HTTP/1.1
Accept: application/json
HTTP/1.1 200 OK
Content-Length: 438

View Slide

Media Types
Media type deﬁnition contains all
information needed to implement a
client and server for a given type.

View Slide

GET / HTTP/1.1
HTTP/1.1 200 OK
Content-Length: 438
{
"statuses":[
{
"body":"neato",
},
{
},
{
},
],
"template":{
"body":"",
"username":""
},
"links":[
{
"rel":"collection",
"href":"/"
}
]}

View Slide

GET /profile HTTP/1.1
HTTP/1.1 200 OK
Content-Length: 438
Content-Type: text/plain
This server emits "microblogging JSON."
## Keys
You can expect the following keys: statuses,
template, links
## Link Relations
You can expect a "collection" relation.
GETing the URI will fetch the list of all
statuses. POSTing a template to this URI will
create a new status.

View Slide

Media Types

View Slide

Media Types
Clients
Servers
Media Type “microblog JSON”

View Slide

“independent
evolution”
Media Types

View Slide

Media Types
https://dev.twitter.com/docs

View Slide

Media Types
RPC

View Slide

Media Types
def reply_to_tweet
tweets = get_list_of_tweets
reply_to = display_to_user(tweets)
reply_data = display_require_form
send_reply(reply_to, reply_data)
end

View Slide

Media Types

View Slide

Media Types


View Slide

Media Types
Hypermedia Affordance
foo


View Slide

Media Types

View Slide

How to recognize process?

View Slide


View Slide

Deleuze’s Materialism
Intensive Property: does not depend
on the amount of substance (density)
Extensive Property: does depend on
amount of substance (mass)

View Slide

Intensive differences drive
processes.

View Slide

M -> C -> M’
C -> M -> C’

View Slide

{
“post”:{
“title”:”Foo”
}
}
{
“post”:{
“title”:”Bar”
}
}

View Slide


View Slide

Media Types
Collection
+JSON,
HAL, XHTML

View Slide

Pagination
The pagination info is included in the Link header. It is important to
follow these Link header values instead of constructing your own
URLs. In some instances, such as in the Commits API, pagination is
based on SHA1 and not on page number.
Link: page=3&per_page=100>; rel="next",
page=50&per_page=100>; rel="last"

View Slide

ID -> URI
"id": 2
vs.
{"rel": "self",
"href": "http://localhost:9292/status/2"}

View Slide

Hypermedia Proxy Pattern
{"links": [
{"rel": "self",
"href": "http://localhost:9292/status/
2"}],
"body":"hello, world",
"location":"Los Angeles"
}

View Slide

Thanks!
@steveklabnik
[email protected]
http://designinghypermediaapis.com
http://words.steveklabnik.com
http://tutorials.jumpstartlab.com

View Slide

Designing Hypermedia APIs

Designing Hypermedia APIs

Steve Klabnik

More Decks by Steve Klabnik

Other Decks in Programming

Featured

Transcript