Download - "API Design at GitHub". Jason Rudolph, GitHub

API

Designat GitHub

@jasonrudolph

stability and agility

stability

Humble Beginnings

{ "rate": { "limit": 5000, "remaining": 4992 }}

$ curl https://api.github.com/rate_limit

https://api.github.com/rate_limit



Some Change is EasyGET /rate_limit



{ "rate": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }}

{ "rate": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }}}


not all requests are created equally


Wither AssumptionsGET /rate_limit



{ "resources": { "core": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }, "search": { "limit": 20, "remaining": 19, "reset": 1379361676 } }}


Wither AssumptionsGET /rate_limit{ "resources": { "core": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }, "search": { "limit": 20, "remaining": 19, "reset": 1379361676 } }}


Wither AssumptionsGET /rate_limit{ "resources": { "core": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }, "search": { "limit": 20, "remaining": 19, "reset": 1379361676 } }}

$.get("https://api.github.com/rate_limit", function(data) { console.log(data["rate"]["limit"]);});

CC BY-NC-SA 2.0h!p://flickr.com/photos/ryandonahue/2342354248



$.get("https://api.github.com/rate_limit", function(data) { console.log(data["rate"]["limit"]);});

Uncaught TypeError: Cannot read property 'limit' of undefined




GET /rate_limit


GET /rate_limit

{ "rate": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }

GET /rate_limit

"resources": { "core": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }, "search": { "limit": 20, "remaining": 19, "reset": 1379361676 } }}

GET /rate_limit

}}

{

{ "rate": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }

GET /rate_limit

"resources": { "core": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }, "search": { "limit": 20, "remaining": 19, "reset": 1379361676 } }}

,

{ "rate": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }, "resources": { "core": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }, "search": { "limit": 20, "remaining": 19, "reset": 1379361676 } }}

"limit": 5000, "remaining": 4992, "reset": 1379363338

"limit": 5000, "remaining": 4992, "reset": 1379363338

GET /rate_limit

compatible > beautiful

stability

agility

CC BY-NC-SA 2.0h!p://flickr.com/photos/ryandonahue/2342354248

API + agile

?

nobody reads

$ curl https://api.github.com/search/code?q=bacon

Be Explicit


Be Explicit

{ "message": "If you would like to help us test the Search API during its preview period, you must specify a custom media type in the 'Accept' header. Please see the docs for full details.", "documentation_url": "http://developer.github.com/v3/search#preview-mode"}

=> HTTP/1.1 415 Unsupported Media Type


Be Explicit




$ curl https://api.github.com/search/code?q=bacon -H 'Accept: application/vnd.github.preview+json'

“Open Sesame”

{ "total_count": 212550, "items": [ ... ]}

$ curl https://api.github.com/search/code?q=bacon -H 'Accept: application/vnd.github.preview+json'

“Open Sesame”

=> HTTP/1.1 200 OK

measure

evolve

sta!-only

sta!-only public preview

sta!-only public preview stable

sta!-only public preview stableAPI

sta!-only public preview stableAPI

sta!-only publicBrowser

agility

stability agility