Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Speaker Deck
PRO
Sign in
Sign up
for free
Launching GitHub's Public GraphQL API
Brooks Swinnerton
May 21, 2017
Technology
2
430
Launching GitHub's Public GraphQL API
Brooks Swinnerton
May 21, 2017
Tweet
Share
More Decks by Brooks Swinnerton
See All by Brooks Swinnerton
bswinnerton
2
46
bswinnerton
4
480
bswinnerton
2
350
bswinnerton
4
88
bswinnerton
0
230
bswinnerton
0
52
bswinnerton
0
79
Other Decks in Technology
See All in Technology
kilometer
0
100
i35_267
0
140
kentaro
1
430
sasakendayo
2
440
minamizaki
0
710
hhiroshell
7
470
takaking22
1
360
shomaekawa
3
1.3k
con_mame
4
2k
ishiayaya
PRO
0
340
asaju7142501
0
360
muras
0
110
Featured
See All Featured
smashingmag
229
18k
andyhume
62
3.4k
lauravandoore
11
1.3k
brettharned
93
3k
morganepeng
17
1.1k
productmarketing
5
660
stephaniewalter
260
11k
reverentgeek
168
7.2k
bryan
30
3.3k
chriscoyier
683
180k
marktimemedia
6
340
keithpitt
401
20k
Transcript
+ a
Hi, I’m Brooks
I work at !
let’s talk about launching the GitHub GraphQL API
How our GraphQL API came to be
March 20th, 2016 proposal submitted
we had dreams of APIv4
multiple resources in one roundtrip
schema introspection
April 6th, 2016 proof of concept done
{ current_user { login repositories(affiliation: "owner") { id name }
} }
April 12th, 2016 New team created
September 14th, 2016 early access
Today >100 million queries/day
We learned some things along the way
Tooling
documentation
https://github.com/gjtorikian/graphql-docs
GraphiQL all-in-one
"but we’re going to need a Ruby client"
github/graphql-client
objects in exchange for a query
collocate our queries with our views
but in Rails
query profiling
query { repository(owner:"rails", name:"rails") { viewerHasStarred } }
{ "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 " } ] } } } }
Authorization
reusing the OAuth logic from our REST API
OAuth scopes are granted to a token
token is used to make a request
familiar to our users
less for us to build
Organization = GraphQL::ObjectType.define do name "Organization" accepted_scopes ["read:org", "admin:org"] end
Organization = GraphQL::ObjectType.define do name "Organization" accepted_scopes ["read:org", "admin:org"] end
but with ✨ GraphQL ✨…
we can analyze the query before resolution
query { organization(login:"github") { members { totalCount } } }
query { organization(login:"github") { members { totalCount } } }
Organization = GraphQL::ObjectType.define do name "Organization" accepted_scopes ["read:org", "admin:org"] end
but this isn’t perfect
in some cases you need to perform resolution first
repo vs public_repo
we’ve introduced an authz layer for resolution
Schema design
first off
there’s more than one
one for new & sensitive features
one for everyone else
Organization = GraphQL::ObjectType.define do name "Organization" accepted_scopes ["read:org"] end
Organization = GraphQL::ObjectType.define do name "Organization" accepted_scopes ["read:org"] visibility :public
end
Organization = GraphQL::ObjectType.define do name "Organization" accepted_scopes ["read:org"] visibility :public
end
CoolNewFeature = GraphQL::ObjectType.define do name "CoolNewFeature" accepted_scopes ["repo"] visibility :internal
end
mandatory first/last arguments on connections
query { viewer { repositories(last:30) { edges { node {
name } } } } }
query { viewer { repositories(last:30) { edges { node {
name } } } } }
is/has/can prefix
query { repository(owner:"rails", name:"rails") { isFork hasIssuesEnabled viewerCanAdminister } }
query { repository(owner:"rails", name:"rails") { isFork hasIssuesEnabled viewerCanAdminister } }
avoiding fields that should be types
query { repository(owner:"rails", name:"rails") { ownerLogin } }
query { repository(owner:"rails", name:"rails") { ownerLogin } }
query { repository(owner:"rails",name:"rails") { owner { login } } }
Feature Parity
schema driven development* *stay tuned!
with our REST API
new features were developed for the UI
then staff-shipped
then released
REST API work started after the ship
but, today…
all new features are built with GraphQL
from the start
CoolNewFeature = GraphQL::ObjectType.define do name "CoolNewFeature" accepted_scopes ["repo"] visibility :internal
end
CoolNewFeature = GraphQL::ObjectType.define do name "CoolNewFeature" accepted_scopes ["repo"] visibility :internal
end
CoolNewFeature = GraphQL::ObjectType.define do name "CoolNewFeature" accepted_scopes ["repo"] visibility :public
end
this allows us to build a true public API
this allows us to build a true public API
this allows us to build a true platform
shared between GitHubbers and integrators
but change is scary
GraphQL-backed REST APIs
this works great for new features
but what about legacy features?
GET https://api.github.com/user
enter Scientist
github/scientist
measure data discrepancies
measure the difference in performance
None
Where we’re headed
static analysis of schema during code review
rate limiting
expose global relay IDs in REST API
preview new fields and objects with headers
Thank you @bswinnerton on Twitter & GitHub @brooks on Slack