API Realtalk

Experience learned from both sides of consuming and building APIs at GitHub.

Transcript

1. API REALTALK @pengwynn wynn.fm
2. WYNNNETHERLAND
3. @pengwynn
4. @pengwynn
5. WYNN.FM
12. I write API wrappers.
14. API #REALTALK
15. API #REALTALK
16. HYPERMEDIA COMES WITH A TAX
17. HYPERMEDIA COMES WITH A TAX #REALTALK
18. YOUR API IS HYPOMEDIA
19. YOUR API IS HYPOMEDIA #REALTALK
20. DEMO
21. DEVELOPERS BUILD URLS
22. DEVELOPERS BUILD URLS [ EVEN WHEN YOU ASK THEM NOT TO ] #REALTALK
23. DEVELOPERS DON'T READ YOUR DOCS
24. DEVELOPERS DON'T READ YOUR DOCS #REALTALK
25. YOU'RE NOT DOGFOODING IT
26. YOU'RE NOT DOGFOODING IT #REALTALK
27. NATIVE APPS
28. BUILD SOMETHING MEANINGFUL WITH YOUR API.
29. Janky BUILD SOMETHING MEANINGFUL WITH YOUR API.
30. Janky Heaven BUILD SOMETHING MEANINGFUL WITH YOUR API.
31. Janky Heaven Monitors BUILD SOMETHING MEANINGFUL WITH YOUR API.
32. Janky Team Heaven Monitors BUILD SOMETHING MEANINGFUL WITH YOUR API.
33. Janky Team Hire Heaven Monitors BUILD SOMETHING MEANINGFUL WITH YOUR API.
34. Janky Team Hire Heaven Monitors Boxen BUILD SOMETHING MEANINGFUL WITH YOUR API.
35. Janky Team Hire Heaven Monitors Boxen Graph Store BUILD SOMETHING MEANINGFUL WITH YOUR API.
36. Janky Team Hire Heaven Monitors Boxen Graph Store BUILD SOMETHING MEANINGFUL WITH YOUR API. Haystack
37. API-POWERED WORKFLOW
45. How GitHub uses the GitHub API.
46. AuthN How GitHub uses the GitHub API.
47. AuthN AuthZ How GitHub uses the GitHub API.
48. AuthN AuthZ Merging How GitHub uses the GitHub API.
49. AuthN AuthZ Merging Commit Status How GitHub uses the GitHub API.
50. AuthN AuthZ Merging Commit Status GFM How GitHub uses the GitHub API.
51. SOMETIMES FOLKS DON'T GET YOU.
52. SOMETIMES FOLKS DON'T GET YOU. #REALTALK
53. GET /me? HTTP/1.1 200 OK Server: example.com Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 200 OK
54. GET /me? HTTP/1.1 200 OK Server: example.com Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 200 OK Developer hears: :OK
55. GET /me? HTTP/1.1 200 OK Server: example.com Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 200 OK Developer hears: :OK
56. GET /me? HTTP/1.1 500 INTERNAL SERVER ERROR Server: example.com Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 500 INTERNAL SERVER ERROR
57. GET /me? HTTP/1.1 500 INTERNAL SERVER ERROR Server: example.com Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 500 INTERNAL SERVER ERROR Developer hears: :DOH
58. GET /me? HTTP/1.1 500 INTERNAL SERVER ERROR Server: example.com Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 500 INTERNAL SERVER ERROR Developer hears: :DOH
59. GET /me? HTTP/1.1 403 FORBIDDEN Server: example.com Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 403 FORBIDDEN
60. GET /me? HTTP/1.1 403 FORBIDDEN Server: example.com Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 403 FORBIDDEN Developer hears: :NOPE
61. GET /me? HTTP/1.1 302 FOUND Server: example.com Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 302 FOUND Location: https://example.com/over/there !
62. GET /me? HTTP/1.1 302 FOUND Server: example.com Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 302 FOUND Location: https://example.com/over/there Developer hears: :WAT
63. /302 me The requested resource resides temporarily under a different URI. Since the redirection might be altered on occasion, the client SHOULD continue to use the Request-URI for future requests. This response is only cacheable if indicated by a Cache- Control or Expires header field.
64. ETAGS ARE COOL. NOBODY USES 'EM.
65. ETAGS ARE COOL. NOBODY USES 'EM. #REALTALK
66. curl -I https://api.github.com/users/defunkt ! HTTP/1.1 200 OK Server: nginx Date: Wed, 12 Sep 2012 14:07:43 GMT Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 200 OK Content-Length: 692 X-Content-Type-Options: nosniff X-RateLimit-Remaining: 4997 X-RateLimit-Limit: 5000 Cache-Control: public, s-maxage=60, max-age=60 Vary: Accept X-GitHub-Media-Type: github.beta ETag: "ef742caec0c19e2169ffb05e7d200d17" Last-Modified: Tue, 11 Sep 2012 02:52:21 GMT
67. curl -I https://api.github.com/users/defunkt ! HTTP/1.1 200 OK Server: nginx Date: Wed, 12 Sep 2012 14:07:43 GMT Content-Type: application/json; charset=utf-8 Connection: keep-alive Status: 200 OK Content-Length: 692 X-Content-Type-Options: nosniff X-RateLimit-Remaining: 4997 X-RateLimit-Limit: 5000 Cache-Control: public, s-maxage=60, max-age=60 Vary: Accept X-GitHub-Media-Type: github.beta ETag: "ef742caec0c19e2169ffb05e7d200d17" Last-Modified: Tue, 11 Sep 2012 02:52:21 GMT Fingerprint
68. curl -I \ -H 'If-None-Match:"ef742caec0c19e2169ffb05e7d200d17" \ https://api.github.com/users/defunkt ! HTTP/1.1 304 Not Modified Server: nginx Date: Wed, 12 Sep 2012 15:51:39 GMT Connection: keep-alive Status: 304 Not Modified X-RateLimit-Limit: 5000 X-Content-Type-Options: nosniff Vary: Accept ETag: "ef742caec0c19e2169ffb05e7d200d17" X-RateLimit-Remaining: 4997 Last-Modified: Wed, 12 Sep 2012 01:38:14 GMT Cache-Control: public, s-maxage=60, max-age=60
69. $ curl -i https://api.github.com/user HTTP/1.1 200 OK Cache-Control: private, max-age=60 ETag: "644b5b0155e6404a9cc4bd9d8b1ae730" Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT Status: 200 OK Vary: Accept, Authorization, Cookie X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4996 ! $ curl -i https://api.github.com/user -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT" ! HTTP/1.1 304 Not Modified Cache-Control: private, max-age=60 Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT Status: 304 Not Modified Vary: Accept, Authorization, Cookie X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4996 ! $ curl -i https://api.github.com/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"' ! HTTP/1.1 304 Not Modified Cache-Control: private, max-age=60 ETag: "644b5b0155e6404a9cc4bd9d8b1ae730" Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT Status: 304 Not Modified Vary: Accept, Authorization, Cookie X-RateLimit-Limit: 5000 X-RateLimit-Remaining: 4996
70. LAST-MODIFIED HEADERS FOR COLLECTIONS ARE HARD TO CALCULATE
71. LAST-MODIFIED HEADERS FOR COLLECTIONS ARE HARD TO CALCULATE #REALTALK
72. N+1 OVER HTTP IS EXPENSIVE, YO
73. N+1 OVER HTTP IS EXPENSIVE, YO #REALTALK
74. YOUR N+1 PROBLEM IS MY FAST LISTING
75. YOUR N+1 PROBLEM IS MY FAST LISTING #REALTALK
76. Attribution Hand designed by Naomi Atkinson from The Noun Project Cereal designed by Jacob Halton from The Noun Project Evil designed by Jim Lears from The Noun Project Console designed by Austin Andrews from The Noun Project Report designed by Doug Cavendish from The Noun Project Television designed by Piero Borgo from The Noun Project Person designed by Paulo Sá Ferreira from The Noun Project Detour designed by Dmitry Baranovskiy from The Noun Project Mime designed by Jonathan C. Dietrich from The Noun Project
77. Thanks.
78. Thanks. Feedback: github.com/pengwynn/pingwynn @pengwynn wynn.fm