Launching GitHub's Public GraphQL API

Transcript

1. + a
2. Hi, I’m Brooks
3. I work at !
4. let’s talk about launching the GitHub GraphQL API
5. How our GraphQL API came to be
6. March 20th, 2016 proposal submitted
7. we had dreams of APIv4
8. multiple resources in one roundtrip
9. schema introspection
10. April 6th, 2016 proof of concept done
11. { current_user { login repositories(affiliation: "owner") { id name } } }
12. April 12th, 2016 New team created
13. September 14th, 2016 early access
14. Today >100 million queries/day
15. We learned some things along the way
16. Tooling
17. documentation
18. https://github.com/gjtorikian/graphql-docs
19. GraphiQL all-in-one
20. "but we’re going to need a Ruby client"
21. github/graphql-client
22. objects in exchange for a query
23. collocate our queries with our views
24. but in Rails
25. query profiling
26. query { repository(owner:"rails", name:"rails") { viewerHasStarred } }
27. { "data": { "repository": { "viewerHasStarred": false } }, "extensions": { "totalDuration": 42.06737782806158, "trackedAssociations": {}, "profiling": { "Repository:viewerHasStarred": { "type": "Boolean!", "sql": [ { "duration": 2.07, "sql": "SELECT 1 AS one FROM `repositories` INNER JOIN `stars` ON `repositories`.`id` = `stars`.`starrable_id` WHERE `stars`.`user_id` = 934497 AND `stars`.`starrable_type` = 'Repository' AND `repositories`.`id` = 8514 LIMIT 1 " } ] } } } }
28. Authorization
29. reusing the OAuth logic from our REST API
30. OAuth scopes are granted to a token
31. token is used to make a request
32. familiar to our users
33. less for us to build
34. Organization = GraphQL::ObjectType.define do name "Organization" accepted_scopes ["read:org", "admin:org"] end
35. Organization = GraphQL::ObjectType.define do name "Organization" accepted_scopes ["read:org", "admin:org"] end
36. but with ✨ GraphQL ✨…
37. we can analyze the query before resolution
38. query { organization(login:"github") { members { totalCount } } }
39. query { organization(login:"github") { members { totalCount } } }
40. Organization = GraphQL::ObjectType.define do name "Organization" accepted_scopes ["read:org", "admin:org"] end
41. but this isn’t perfect
42. in some cases you need to perform resolution first
43. repo vs public_repo
44. we’ve introduced an authz layer for resolution
45. Schema design
46. first off
47. there’s more than one
48. one for new & sensitive features
49. one for everyone else
50. Organization = GraphQL::ObjectType.define do name "Organization" accepted_scopes ["read:org"] end
51. Organization = GraphQL::ObjectType.define do name "Organization" accepted_scopes ["read:org"] visibility :public end
52. Organization = GraphQL::ObjectType.define do name "Organization" accepted_scopes ["read:org"] visibility :public end
53. CoolNewFeature = GraphQL::ObjectType.define do name "CoolNewFeature" accepted_scopes ["repo"] visibility :internal end
54. mandatory first/last arguments on connections
55. query { viewer { repositories(last:30) { edges { node { name } } } } }
56. query { viewer { repositories(last:30) { edges { node { name } } } } }
57. is/has/can prefix
58. query { repository(owner:"rails", name:"rails") { isFork hasIssuesEnabled viewerCanAdminister } }
59. query { repository(owner:"rails", name:"rails") { isFork hasIssuesEnabled viewerCanAdminister } }
60. avoiding fields that should be types
61. query { repository(owner:"rails", name:"rails") { ownerLogin } }
62. query { repository(owner:"rails", name:"rails") { ownerLogin } }
63. query { repository(owner:"rails",name:"rails") { owner { login } } }
64. Feature Parity
65. schema driven development* *stay tuned!
66. with our REST API
67. new features were developed for the UI
68. then staff-shipped
69. then released
70. REST API work started after the ship
71. but, today…
72. all new features are built with GraphQL
73. from the start
74. CoolNewFeature = GraphQL::ObjectType.define do name "CoolNewFeature" accepted_scopes ["repo"] visibility :internal end
75. CoolNewFeature = GraphQL::ObjectType.define do name "CoolNewFeature" accepted_scopes ["repo"] visibility :internal end
76. CoolNewFeature = GraphQL::ObjectType.define do name "CoolNewFeature" accepted_scopes ["repo"] visibility :public end
77. this allows us to build a true public API
78. this allows us to build a true public API
79. this allows us to build a true platform
80. shared between GitHubbers and integrators
81. but change is scary
82. GraphQL-backed REST APIs
83. this works great for new features
84. but what about legacy features?
85. GET https://api.github.com/user
86. enter Scientist
87. github/scientist
88. measure data discrepancies
89. measure the difference in performance
91. Where we’re headed
92. static analysis of schema during code review
93. rate limiting
94. expose global relay IDs in REST API
95. preview new fields and objects with headers
96. Thank you
 @bswinnerton on Twitter & GitHub @brooks on Slack