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.

2. API
Design
at GitHub

3. 
@jasonrudolph

4. 
stability and agility

5. stability

7. 
Humble Beginnings
{
"rate": {
"limit": 5000, "remaining": 4992
}
}
$ curl https://api.github.com/rate_limit

8. 


9. 
{
"rate": {
"limit": 5000, "remaining": 4992
}
}
Some Change is Easy
GET /rate_limit

10. 
{
"rate": {
"limit": 5000, "remaining": 4992
}
}
Some Change is Easy
GET /rate_limit
{
"rate": {
"limit": 5000, "remaining": 4992, "reset": 1379363338
}
}

11. 
{
"rate": {
"limit": 5000, "remaining": 4992, "reset": 1379363338
}
}}
Some Change is Easy
GET /rate_limit

12. 
not all requests are created equally

13. 
{
"rate": {
"limit": 5000, "remaining": 4992, "reset": 1379363338
}
}}
Wither Assumptions
GET /rate_limit

14. 
{
"rate": {
"limit": 5000, "remaining": 4992, "reset": 1379363338
}
}}
Wither Assumptions
GET /rate_limit

15. 
{
"rate": {
"limit": 5000, "remaining": 4992, "reset": 1379363338
}
}}
Wither Assumptions
GET /rate_limit
{
"resources": {
"core": {
"limit": 5000, "remaining": 4992, "reset": 1379363338
},
"search": {
"limit": 20, "remaining": 19, "reset": 1379361676
}
}
}

16. 
{
"rate": {
"limit": 5000, "remaining": 4992, "reset": 1379363338
}
}}
Wither Assumptions
GET /rate_limit
{
"resources": {
"core": {
"limit": 5000, "remaining": 4992, "reset": 1379363338
},
"search": {
"limit": 20, "remaining": 19, "reset": 1379361676
}
}
}

17. 
{
"rate": {
"limit": 5000, "remaining": 4992, "reset": 1379363338
}
}}
Wither Assumptions
GET /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"]);
});

18. CC BY-NC-SA 2.0
http://flickr.com/photos/ryandonahue/2342354248

19. 
{
"resources": {
"core": {
"limit": 5000, "remaining": 4992, "reset": 1379363338
},
"search": {
"limit": 20, "remaining": 19, "reset": 1379361676
}
}
}
Wither Assumptions
GET /rate_limit
$.get("https://api.github.com/rate_limit", function(data) {
console.log(data["rate"]["limit"]);
});
Uncaught TypeError: Cannot read property 'limit' of undefined

20. 
{
"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

21. 


22. 
{
"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
}}
{

23. 
{
"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
}
}
}
,

24. 
{
"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

25. 
compatible > beautiful

26. stability

27. agility

31. CC BY-NC-SA 2.0
http://flickr.com/photos/ryandonahue/2342354248

32. 
API + agile
?

33. 
nobody reads

34. 
$ curl https://api.github.com/search/code?q=bacon
Be Explicit

35. 
$ 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

36. 
$ 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

37. 
{
"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

38. 
{
"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

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

40. 
{
"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

41. 
measure

43. 
evolve

44. staff-only

45. staff-only  public preview

46. staff-only  public preview  stable

47. staff-only  public preview  stable
API

48. staff-only  public preview  stable
API
staff-only  public
Browser


49. agility

50. stability agility

51. stability agility

53. 