API Realtalk

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

Transcript

1. API REALTALK
   @pengwynn
   wynn.fm
   

   View Slide

2. WYNNNETHERLAND
   

   View Slide

3. @pengwynn
   

   View Slide

4. @pengwynn
   

   View Slide

5. WYNN.FM
   

   View Slide

6. View Slide

7. View Slide

8. View Slide

9. View Slide

10. View Slide

11. View Slide

12. I write API wrappers.
    

    View Slide

13. View Slide

14. API #REALTALK
    

    View Slide

15. API #REALTALK
    

    View Slide

16. HYPERMEDIA COMES WITH A TAX
    

    View Slide

17. HYPERMEDIA COMES WITH A TAX
    #REALTALK
    

    View Slide

18. YOUR API IS HYPOMEDIA
    

    View Slide

19. YOUR API IS HYPOMEDIA
    #REALTALK
    

    View Slide

20. DEMO
    

    View Slide

21. DEVELOPERS BUILD URLS
    

    View Slide

22. DEVELOPERS BUILD URLS
    [ EVEN WHEN YOU ASK THEM NOT TO ]
    #REALTALK
    

    View Slide

23. DEVELOPERS DON'T READ YOUR DOCS
    

    View Slide

24. DEVELOPERS DON'T READ YOUR DOCS
    #REALTALK
    

    View Slide

25. YOU'RE NOT DOGFOODING IT
    

    View Slide

26. YOU'RE NOT DOGFOODING IT
    #REALTALK
    

    View Slide

27. NATIVE APPS
    

    View Slide

28. BUILD SOMETHING MEANINGFUL WITH YOUR API.
    

    View Slide

29. Janky
    BUILD SOMETHING MEANINGFUL WITH YOUR API.
    

    View Slide

30. Janky
    Heaven
    BUILD SOMETHING MEANINGFUL WITH YOUR API.
    

    View Slide

31. Janky
    Heaven
    Monitors
    BUILD SOMETHING MEANINGFUL WITH YOUR API.
    

    View Slide

32. Janky
    Team
    Heaven
    Monitors
    BUILD SOMETHING MEANINGFUL WITH YOUR API.
    

    View Slide

33. Janky
    Team
    Hire
    Heaven
    Monitors
    BUILD SOMETHING MEANINGFUL WITH YOUR API.
    

    View Slide

34. Janky
    Team
    Hire
    Heaven
    Monitors
    Boxen
    BUILD SOMETHING MEANINGFUL WITH YOUR API.
    

    View Slide

35. Janky
    Team
    Hire
    Heaven
    Monitors
    Boxen
    Graph Store
    BUILD SOMETHING MEANINGFUL WITH YOUR API.
    

    View Slide

36. Janky
    Team
    Hire
    Heaven
    Monitors
    Boxen
    Graph Store
    BUILD SOMETHING MEANINGFUL WITH YOUR API.
    Haystack
    

    View Slide

37. API-POWERED WORKFLOW
    

    View Slide

38. View Slide

39. View Slide

40. View Slide

41. View Slide

42. View Slide

43. View Slide

44. View Slide

45. How GitHub uses the GitHub API.
    

    View Slide

46. AuthN
    How GitHub uses the GitHub API.
    

    View Slide

47. AuthN
    AuthZ
    How GitHub uses the GitHub API.
    

    View Slide

48. AuthN
    AuthZ
    Merging
    How GitHub uses the GitHub API.
    

    View Slide

49. AuthN
    AuthZ
    Merging
    Commit Status
    How GitHub uses the GitHub API.
    

    View Slide

50. AuthN
    AuthZ
    Merging
    Commit Status
    GFM
    How GitHub uses the GitHub API.
    

    View Slide

51. SOMETIMES FOLKS DON'T GET YOU.
    

    View Slide

52. SOMETIMES FOLKS DON'T GET YOU.
    #REALTALK
    

    View Slide

53. GET /me?
    HTTP/1.1 200 OK
    Server: example.com
    Content-Type: application/json; charset=utf-8
    Connection: keep-alive
    Status: 200 OK
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

59. GET /me?
    HTTP/1.1 403 FORBIDDEN
    Server: example.com
    Content-Type: application/json; charset=utf-8
    Connection: keep-alive
    Status: 403 FORBIDDEN
    

    View Slide

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
    

    View Slide

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
    !
    

    View Slide

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
    

    View Slide

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.
    

    View Slide

64. ETAGS ARE COOL. NOBODY USES 'EM.
    

    View Slide

65. ETAGS ARE COOL. NOBODY USES 'EM.
    #REALTALK
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

70. LAST-MODIFIED HEADERS FOR COLLECTIONS
    ARE HARD TO CALCULATE
    

    View Slide

71. LAST-MODIFIED HEADERS FOR COLLECTIONS
    ARE HARD TO CALCULATE
    #REALTALK
    

    View Slide

72. N+1 OVER HTTP IS EXPENSIVE, YO
    

    View Slide

73. N+1 OVER HTTP IS EXPENSIVE, YO
    #REALTALK
    

    View Slide

74. YOUR N+1 PROBLEM IS MY FAST LISTING
    

    View Slide

75. YOUR N+1 PROBLEM IS MY FAST LISTING
    #REALTALK
    

    View Slide

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
    

    View Slide

77. Thanks.
    

    View Slide

78. Thanks.
    Feedback: github.com/pengwynn/pingwynn
    @pengwynn
    wynn.fm
    

    View Slide