"api design at github". jason rudolph, github
DESCRIPTION
Get a behind-the-scenes look at development on the GitHub API team. Developers and businesses rely on the stability and consistency of the GitHub API for critical tasks. Changes to the API could break production deployments (or continuous integration, authentication, etc.) for thousands of businesses. And yet, GitHub.com continues to evolve, improving existing features, and adding new ones. The GitHub API needs to evolve as well. We'll explore the design philosophies and techniques that we use to provide a reliable API, while continuing to ship improvements every day.TRANSCRIPT
API
Designat GitHub
@jasonrudolph
stability and agility
stability
Humble Beginnings
{ "rate": { "limit": 5000, "remaining": 4992 }}
$ curl https://api.github.com/rate_limit
{ "rate": { "limit": 5000, "remaining": 4992 }}
Some Change is EasyGET /rate_limit
{ "rate": { "limit": 5000, "remaining": 4992 }}
Some Change is EasyGET /rate_limit
{ "rate": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }}
{ "rate": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }}}
Some Change is EasyGET /rate_limit
not all requests are created equally
{ "rate": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }}}
Wither AssumptionsGET /rate_limit
{ "rate": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }}}
Wither AssumptionsGET /rate_limit
{ "rate": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }}}
Wither AssumptionsGET /rate_limit
{ "resources": { "core": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }, "search": { "limit": 20, "remaining": 19, "reset": 1379361676 } }}
{ "rate": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }}}
Wither AssumptionsGET /rate_limit{ "resources": { "core": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }, "search": { "limit": 20, "remaining": 19, "reset": 1379361676 } }}
{ "rate": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }}}
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
{ "resources": { "core": { "limit": 5000, "remaining": 4992, "reset": 1379363338 }, "search": { "limit": 20, "remaining": 19, "reset": 1379361676 } }}
Wither AssumptionsGET /rate_limit
$.get("https://api.github.com/rate_limit", function(data) { console.log(data["rate"]["limit"]);});
Uncaught TypeError: Cannot read property 'limit' of undefined
{ "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 } }}
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
$ curl https://api.github.com/search/code?q=bacon
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
$ curl https://api.github.com/search/code?q=bacon
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"}
{ "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
{ "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"}
$ curl https://api.github.com/search/code?q=bacon
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
{ "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"}
{ "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"}
$ curl https://api.github.com/search/code?q=bacon
Be Explicit
=> HTTP/1.1 415 Unsupported Media Type
$ 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
stability agility
