GitHub recently introduced at their Github Universe conference the alpha release of their new API, written in Facebook's GraphQL (a query language that allows for self-service API contracts). GitHub writes in its engineering blog that its main reason for switching API paradigms is lack of scalability with their existing RESTful contracts. REST is unable to provide the flexibility they need to cater to all of their many distinct consumers simultaneously while maintaining a low maintenance overhead.
GitHub's announcement that it will migrate its existing API to GraphQL coincides with Facebook's decision several days later to finally remove the "technical preview" moniker from its service. Although GraphQL has been used by Facebook in production since 2012, it has been technically in "preview" since it was open sourced up until its recent mid September release. The community at large has had mixed responses to GraphQL, with some claiming that it places unfair additional complexity and management on server side code, with others praising its ability to isolate various individual consumer's data consumption needs from the core data itself, allowing APIs to be more scalable and versatile. In GitHub's engineering blog, GitHub writes of their current API, "Despite all the information we provided, we heard from integrators that our REST API...wasn't very flexible. It sometimes required two or three separate calls to assemble a complete view of a resource. It seemed like our responses simultaneously sent too much data and didn't include data that consumers needed." GitHub hints here that in scenarios where there are large numbers of distinct consumers who need complex amounts of underlying data GraphQL is a great fit, whereas providing an API for a simple website with limited developer consumption may not show off the best of GraphQL compared to REST.
In GitHub's engineering blog, GitHub points to its API history starting in 2008. GitHub mentions that its first RESTful API served as an example for numerous companies crafting their own REST APIs who were looking for a solid template. GitHub hopes that GraphQL, like its first foray into REST, will serve as an example to other developers and companies looking for a great way to take advantage of their complex data needs across multiple consumers. As one of GraphQL's original contributors, Lee Byron said in the InfoQ article following GraphQL's technical preview release, "The community isn't just using GraphQL, but building it too." GitHub, as one of the first mainstream consumers of GraphQL has been transforming GraphQL since its inception. GraphQL has been translated through GitHub from its original Javascript into a wide number of languages, from Java to C# to Ruby (which GitHub itself is using) and now has a plethora of associated open source tooling on the platform.
While GitHub's main reason for switching over to GraphQL appears to be scalability in meeting varying consumer needs, they also mention a large number of additional benefits. GitHub writes in their blog, "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." With the amount of data that GitHub surfaces today, generated documentation and introspection go a long way in helping data consumption. While tools like Swagger are immensely helpful in documenting RESTful APIs, they do require manual annotations to be created throughout the code base that can easily become as stale as code comments. All of GraphQL's included tooling allows Github to release their software alongside corresponding API changes and necessary API documentation simultaneously, which is a big win for both GitHub and its consumers.
