JSON API – Convention driven API design
JSON API – Convention driven API design
0 1
conventions_presentation
A talk about JSON API.On Github json-api / conventions_presentation
JSON API
Convention driven API design
@steveklabnik
The Zen of Python: explicit is better than implicit
Ruby on Rails: Convention over configuration
Media types
- text/plain
- text/html
- application/json
- image/png
Zen or CoC?
Have our cake and eat it too
Media types are explicit conventions.
Zen or CoC?
Media types are explicit because we have Content-Type and the related RFC.
Zen or CoC?
Media types are conventions because we have a shared understanding of processing rules.
Common API media types
- application/json
Problems with JSON
JSON's minimalism can only encode the vague structure of your data.
This has led to an explosion of bespoke, artisanal, hand-crafted APIs.
Problems with JSON
The purpose of the Content-Type field is to describe the data contained in the body fully enough that the receiving user agent can pick an appropriate agent or mechanism to present the data to the user, or otherwise deal with the data in an appropriate manner.Problems with JSON
Any sufficiently advanced API contains an ad-hoc, informally specified implementation of some media type that extends JSON.
Problems with JSON
application/json leads to bikeshedding. Bikeshedding leads to anger. Anger leads to hate. Hate leads to suffering.
Solution:
Solution:JSON API
JSON API
JSON API assumes that you have some collection of data that you'd like to synchronize across a network boundary.
Its conventions allow you to builda smart client that minimizes requests.
JSON API
It's based on real code used by real sites.We use it at my employer to process payments.If it's good enough for money, it's good enough for your API.
It's co-authored by Yehuda Katz and myself.
JSON API
Here's what JSON API (in the ID style) looks like:
{
"posts": [{
"id": "1",
"title": "Rails is Omakase",
"links": {
"author": "9",
"comments": [ "5", "12", "17", "20" ]
}
}]
}
JSON API
and in the URL style:
{
"posts": [{
"id": "1",
"title": "Rails is Omakase",
"links": {
"author": "http://example.com/people/1",
"comments": "http://example.com/comments/5,12,17,20"
}
}]
}
JSON API
URI Templates:
{
"links": {
"posts.comments": "http://example.com/posts/{posts.id}/comments"
},
"posts": [{
"id": "1",
"title": "Rails is Omakase"
}, {
"id": "2",
"title": "The Parley Letter"
}]
}
JSON API
Not just for GET
GET /photos
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"photos": [{
"id": "1",
"title": "Mustaches on a Stick"
"src": "http://example.com/images/mustache.png"
}]
}
JSON API
Not just for GET
POST /photos
Content-Type: application/vnd.api+json
Accept: application/vnd.api+json
{
"photos": [{
"title": "Ember Hamster",
"src": "http://example.com/images/productivity.png"
}]
}
JSON API
Not just for GET
GET /photos
HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
{
"photos": [{
"id": "1",
"title": "Mustaches on a Stick"
"src": "http://example.com/images/mustache.png"
}, {
"id": "2",
"title": "Ember Hamster",
"src": "http://example.com/images/productivity.png"
}]
}
JSON API
Conclusion
- Media types are explicit conventions.
- Conventions improve productivity by reducing bikeshedding.
- Conventions pave the path for reusability.
- Pick a media type that fits your application.
- If you don't know, try JSON API.