Introducing the GraphQL Guide
Today I’m happy to announce the beta release of The GraphQL Guide, a book that I’ve been working on with Loren Sands-Ramshaw! The Guide shows you why GraphQL APIs are the true successor to REST APIs. You can purchase the beta at https://GraphQL.guide.
We’ll be looking at the core fundamentals of GraphQL along with strategies for how to implement it (client-side with Apollo and server-side in Node.js). Additionally, we’ll be exploring different situations in which GraphQL can be used (on mobile with React Native or Java/Swift, and on the web with either React or Vue).
We currently have four chapters ready, including the introduction and the React chapter, and we’re continuing to work on the rest — which will include videos and an example app! Your feedback on the continued development of this book would be greatly appreciated. We’re writing it completely independently so that we can maintain full creative control, so please let us know what you want to read!
I want to provide a bit of background as to why I’ve become so enamored with GraphQL and why I truly feel that it’s going to change how we design and build APIs.
Ever since GraphQL was announced in late 2015, my fellow engineers and I at Khan Academy had been buzzing about its potential. We were very early adopters of React (we were the first company outside of Facebook to use it, and one of our engineers, Sophie Alpert, now manages the React team at Facebook). We started having discussions about GraphQL in our bi-weekly Web Frontend Guild meeting — people were playing with it in their spare time and learning about it at conferences like React.js Conf. During our twice-yearly hackathons, engineers, such as Emily Eisenberg, completed experiments to see how GraphQL might work on our platform (especially when tied together as a complete Progressive Web App).
In early 2016 we had reorganized much of the product team at Khan Academy into “initiatives.” I was working on the initiative centered around classrooms (focusing on both teachers and students) and, unfortunately, much of our codebase was outdated and needed to be rewritten. It was a perfect time to explore using GraphQL in a greenfield scenario to see both how we liked using it in practice and how quickly we could get up to speed.
For all of our history, Khan Academy, like much of the web industry, had used custom REST APIs to deliver data to our clients. Parts of our API are public but the vast majority of it is private, accessed via JavaScript (typically in our React + Redux stack) to render our pages on the client-side. This practice resulted in an explosion of API endpoints covering every permutation of every page. Our REST endpoints either became fractured (requiring us to make many API requests on every page load) or bloated (with a single API request returning far more data than was needed).
It was in this world that GraphQL’s promises were especially compelling. GraphQL offers a way to push all of the logic for specifying data requirements onto the client, and in return, the server will execute the (highly structured) data query against a known schema. The end result is a vastly simplified backend that also empowers the client to execute whichever queries they need.
We implemented a generic GraphQL platform to use at Khan Academy and immediately started to use it in our classroom products. Our development practices changed overnight. The server implementations were dramatically simplified and became closer to write-once, whereas in the past they had required constant updates and tweaks during development. It meant that our frontend engineers got to focus more on writing client-side code and thinking about data requirements, rather than also having to juggle writing server-side code just to update an API. Today we’re using GraphQL in more and more places: we are transitioning older pages over to use GraphQL and have a mandate in place that all new pages need to use GraphQL.
The benefits that we’ve reaped have been so substantial, even though it’s still early days. We’re writing new products faster, we’re able to rapidly iterate on designs, and we’re keeping our server implementation slim.
The experience of rolling out GraphQL at Khan Academy is what drove me to want to write about it. I look at how well it’s worked for us and read stories about how GraphQL has changed other organizations, and I can only think that GraphQL is going to dramatically change how we all build APIs going forward. REST APIs now feel quite antiquated by comparison. Hopefully our book helps to convince you of this!
Once we’ve convinced you of GraphQL’s power we’ll be teaching you all sorts of strategies for both using and implementing GraphQL in your projects (server, client, web, and mobile). We’re hoping that The GraphQL Guide will become an indispensable resource for you to learn all about how incredible GraphQL is!
