For many years, REST has been the standard pattern for designing APIs. Whilst it has many benefits, REST has been proven to be relatively inflexible and doesn’t stand up well when client requirements change. GraphQL is an alternative approach which addresses these flexibility issues.
GraphQL is a relatively new API design pattern that can be used as an alternative to the traditional REST API. It was built by Facebook and has powered their mobile apps since 2012. Facebook open-sourced it in 2015 and the pattern has steadily gained usage and popularity in the industry in order to feed data to web and mobile clients.
Here at The Distance, we’ve started to use GraphQL in our most recent projects and our developers have seen the huge benefits in using it to get data to our mobile apps in the most efficient way possible. In this blog post we’ll take a quick overview of GraphQL, look at its pros and cons and the excellent tooling available.
Why GraphQL?
GraphQL is a query language and its big advantage is its flexibility. It allows a client to define a single query specifying exactly what data it requires. The back-end will then return a JSON object containing exactly this data, in precisely the same nested structure as the query. The benefits of this are huge. Gone are the days of having to call multiple REST endpoints to get the data for a single screen, and ending up with a ton of surplus data that is never used. Instead, a single call will get all the data required for the screen. This solves the problem commonly known as overfetching.
Consider an instance where a client wishes to change their requirements for a particular screen. Say they wish to add an additional list to the screen which is populated with data from a server. With a REST API approach, the back-end dev would have to change an existing endpoint or create a new endpoint to feed this data. The front-end dev would then have to call this endpoint, parse the data and then display it on the screen – quite a bit of work for a relatively small change. In contrast, with a GraphQL approach, the back-end dev would just need to expose the new data to the existing endpoint. The front-end dev would then just need to change the existing query to fetch the data. Far more efficient and far more flexible.
GraphQL is also pretty straightforward to learn. And with a rich ecosystem developing, there is excellent tooling, documentation and tutorials available. Given companies like Facebook, GitHub, Shopify and Twitter all use GraphQL, these resources are only likely to continue growing.
Disadvantages with GraphQL
Whilst GraphQL has many advantages, like anything, it also has a few disadvantages.
The first of which is rate limiting. Given that a client can specify the exact data it requires, a GraphQL operation can be of varying load, anywhere from cheap to expensive. Therefore, unlike a REST API where you can just specify how many times an endpoint can be hit per day, it’s much more difficult to rate limit a GraphQL back-end.
The second is that you need to learn how to use GraphQL. Whilst this may seem like an obvious thing, there is always a time-cost debt in learning new technologies.
The third is that, given queries are sent from the client, we need to use some sort of client library to handle the GraphQL libraries. This results in extra code in the client.
GraphQL Tooling
One of the most popular and widely used client libraries is Apollo. Apollo is a networking library that makes it easy to consume any GraphQL schema, fetch and mutate data from any GraphQL endpoint and even auto-generates data models for you. It has great documentation, code examples, and is supported on many different platforms including native iOS, native Android and JavaScript frameworks such as React, Angular and Vue.
I personally have only used the Apollo Framework for iOS and have overall been very impressed with it. Whilst I experienced a few issues with the initial setup, my experience since then has been really positive and it has been great to use.
Another awesome tool is GraphQL Playground. This is the equivalent of Postman for a REST API and allows you to test out an endpoint, verify the responses and also view the schema. This is a must-have if you’re working with a GraphQL back-end.
Summary
In summary, GraphQL is a really cool, powerful technology that can be used to power your apps. If you haven’t already done so, we’d strongly recommend you check it out, play around with it and see for yourself the awesome benefits it offers. We reckon it will be powering our mobile apps for some time to come.
The new version of our backend platform The Core (v4) is designed around AWS microservices and GraphQL. For more info or advice on GraphQl feel free to contact us.
Useful Links
[1] GraphQL – https://graphql.org
[2] GraphQL vs REST – https://blog.apollographql.com/graphql-vs-rest-5d425123e34b
[3] GraphQL and Apollo on iOS – https://www.raywenderlich.com/595-getting-started-with-graphql-apollo-on-ios
[4] Apollo – https://www.apollographql.com
Article by James Shaw, iOS Developer at The Distance HQ.