The GitHub GraphQL API
Jonas Helfer
In September of 2016 GitHub casually dropped some big news when they officially announced their new GraphQL API and made it available to everyone in early access.
In this post I’ll explain the most important things you need to know about GitHub’s GraphQL API:
- Why it matters
- What it looks like (also check out the video tour!)
- How you can use it
- What’s coming next
If you don’t yet know what GraphQL is, go check out the excellent introduction on graphql.org before reading the rest of this post. You’ll get more out of it.
Why it matters
For years, GitHub’s REST API has been used by others as a great example of a well-designed REST API, and many companies modeled their REST API after GitHub’s.
If GitHub’s REST API was so good, why are they moving to GraphQL? For the same reasons that many other companies have started adopting GraphQL. You can read the details in their announcement post, but the gist of it is this:
- Where REST requires many requests, GraphQL takes just one
- With REST, you request too much or too little data; with GraphQL you request exactly what you need
- REST often turns into a maze of poorly-documented endpoints; GraphQL is strongly-typed and self-documenting
In the words of the GitHub platform team:
GraphQL represents a massive leap forward for API development. Type safety, introspection, generated documentation, and predictable responses benefit both the maintainers and consumers of our platform. We’re looking forward to our new era of a GraphQL-backed platform, and we hope that you do, too!
Thanks to GraphQL, GitHub no longer needs to separately maintain a public and a private API. Instead there will be just one API, used for both.
GitHub’s announcement is so significant because their new API is the first large-scale, public GraphQL API, and where GitHub goes many others will follow. On top of that, other notable companies are already using GraphQL, including Facebook, Twitter, Intuit, Shopify, and many more. There’s so much interest that the first GraphQL conference ever is coming to San Francisco this October.
But enough about why this is so exciting, let’s take a look at their actual API.
What it looks like
If you sign their prerelease agreement, you get early access to the GitHub GraphQL API. I did just that, and then headed straight to the API Explorer. Those familiar with GraphQL will recognize it as GraphiQL.
After a couple seconds of typing, I sent my first query and got back a response — it worked! I could have used GraphiQL to explore the schema, but it’s not the easiest way to get a quick overview, so I turned to the API documentation to find out what queries or mutations I could make. The starting points for queries were pretty much as expected: you can search for things, look up users and organizations, and get info about yourself using the viewer query. From there you can drill deeper and get lists of repositories, which in turn let you get PRs, issues, comments, reactions (the emojis), forks, branches, commits and even the Git trees of individual commits. And that’s really only the tip of the iceberg. Pretty cool, right?
Next up, I took a look at the mutations — GraphQL’s way of modifying data. The selection there is a lot more limited. Right now, the only things you can do are comment on issues, add reactions to comments, subscribe/unsubscribe from issues, and manage projects — a new feature GitHub introduced yesterday, and which is powered by GraphQL.
Of course, I had to try posting a comment via the new GraphQL API:
Here’s a link to the issue. Go give it a try, and see if you can post to it via GitHub’s GraphQL API!
Overall, I think the existing parts of the API are already in excellent shape, and there were just a few rough edges:
- The API documentation was slightly outdated and incomplete in places. I worked around it by using the introspection query to print myself a neat little schema in GraphQL schema language (see the schema).
- Connections (a type of pagination) are used extensively, which can make initial interaction with the API quite confusing for people who are not familiar with connections.
- All mutations take only one input argument, which makes them harder to write and read. This was done because of a limitation in Relay, but Relay 2 is going to remove that limitation, and Apollo Client already supports multiple arguments today.
Edit (9/16): I felt like this post didn’t adequately cover how powerful the GraphQL API is, so I made a quick video tour for anyone who wants to see more:
How you can use it
Once you’ve signed the prerelease agreement, you can start building your own apps against GitHub’s GraphQL API. Technically you can send your GraphQL queries as simple strings in a POST request, but your life is going to be a lot easier if you use a GraphQL client like Apollo Client or Relay.
To make your life even easier, we’ve built an example mobile app with React Native. It’s a small GitHub issue reader that demonstrates how you can use the GraphQL API. You’re more than welcome to contribute to it by adding features or fixing bugs!
What’s coming next
This is just the start of GitHub’s GraphQL API, and there’s a lot more to come. The API will be refined during early access, and the GitHub team hopes to add support for features like batching, subscriptions and deferring to their server (Apollo Client already supports batching and subscriptions!)
If all that talk about GraphQL got you curious, you’ll definitely want to look at the following posts and resources to learn more about it.
Blog posts + tutorials:
- Why GraphQL is the future
- GraphQL concepts visualized
- GraphQL: the next generation of API design
- Tutorial: how to build your own GraphQL server
- … and more on our blog
Resources:
Last but not least: As we mentioned before, the first-ever GraphQL conference is happening in SF on October 26th! GitHub’s Brandon Black will talk more about how his team built the new GraphQL API, along with speakers from Facebook Open Source, Angular, Apollo, and more.
