The Why Behind The Github GraphQL API

I wrote a skeptical piece the other day about GraphQL, which I followed up with another post saying I would keep an open mind. I've added GraphQL to my regular monitoring of the space, but I don't have its own research area yet, but if the conversation keeps expanding I will. A recent expansion in the GraphQL conversation for me was Github releasing the GitHub GraphQL API.

In the release blog post, from Github they provide exactly what I'm looking for in the GraphQL conversation--the reasons why they chose to start supporting GraphQL. In their post Github describes some of the challenges API consumers were having with the existing API, which led them down the GraphQL path:

  • sometimes required two or three separate calls to assemble a complete view of a resource
  • responses simultaneously sent too many data and didn’t include data that consumers needed

They also talk about some of what they wanted to accomplish:

  • wanted to identify the OAuth scopes required for each endpoint
  • wanted to be smarter about how our resources were paginated
  • wanted assurances of type-safety for user-supplied parameters
  • wanted to generate documentation from our code
  • wanted to generate clients

Github says they "studied a variety of API specifications built to make some of this easier, but we found that none of the standards totally matched our requirements" and felt that "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". Some interesting points to consider, as I work to understand the benefits GraphQL brings to the table.

I'm still processing the entire story behind their decision to go GraphQL, and will share any more thoughts I'm having in future blog posts. With this major release from Github, I am now keeping an eye out for other providers who are headed in this direction. Hopefully, they will be as transparent about their reasons why as Github has--this kind of storytelling around API design and deployment is important for the rest of the API community to learn from.