A Brief 10-Point Guide to GraphQL

When I’m learning new about new technologies, one of the first things, I’ll do is write a numbered list 1–10 and then fill that numbered list in with points about that particular technology. I realised that these lists might be useful to others so I’m going to start posting them. This week I looked at GraphQL.

1. GraphQL can be best thought of as a middleware between your clients and your servers. The idea behind GraphQL is to have a system which sits between your clients and your API and allows the requesting of data through itself. It has an in-built query language which allows your to create requests and GraphQL will handle the fetching and composing of the data.

2. One of the primary reasons to use GraphQL is that it simplifies dealing with your backend APIs. For example, a common pattern to find in applications is the need to request data from two or more distinct sources and compose them to be processed together. For example, you might have images stored in one database and text stored in another. Using GraphQL enables you to have a single query to get the data from both of the sources and return a single response, which greatly simplifies your code has you don’t have to deal with the complexities of handling multiple requests and waiting all of them before processing the data together.

3. One of the oft-quoted benefits of GraphQL is that it decouples you from your existing API implementation. This means that with GraphQL you can easily swap out the implementation of your existing API for another one and everything will continue hunky dory. However, the seldom mentioned caveat to this is that you are necessarily coupling yourself to GraphQL itself

4. Data savings are another benefit of using GraphQL. With GraphQL, you don’t need to make multiple calls to your API as you would with REST. You can query for only the data you want: GraphQL can aggregate data from multiple sources for you and it will only return the data that you need. The result of this is data savings for each API call, which leads to improved performance of your application overall.

5. GraphQL enables increased speed of development. The reason for this is that because GraphQL decouples your client from your API, different teams also become decoupled, meaning there is a reduced need of coordination between teams to get development done. To give an example, instead of the frontend team needing to coordinate with the backend team to update or add a new REST endpoint, they can simply develop their new frontend functionality using GraphQL to get the exact data they need.

6. Another benefit of using GraphQL is that there is reduced need for filtering data. Often when developing a new feature of an application, a developer will have to filter and aggregate existing data to generate the new data required for the new feature. All of this leads to additional code, which incurs additional costs both in terms of development time and maintenance time. With GraphQL this is unnecessary as GraphQL handles the aggregation and filtering of data for free.

7. One of the drawbacks of GraphQL is that there is a need for a fair amount of boilerplate code. For example you will often need to write a Resolver, a query, a mutation, and a schema.

8. Benefit — Strong typing — GraphQL’s query language is strongly typed. This is benefit because it provides a common contract for communication between the client of an application and the backend. This helps facilitate independent development of both the frontend and backend because the strong typing of GraphQL provides a solid and predictable foundation on which to base the target of future system states. In other words, developer can write new code knowing that GraphQL will be able to provide the data they require and they will know the format of that data.

9. Another disadvantage of GraphQL is that error handling is somewhat more difficult and cumbersome than it is with REST. If you GraphQL query errors, it doesn’t return a 5xx error code or even a 4xx error code, but instead it always returns a 200 success code. The error will be in the JSON response itself. This is weird. It’s something that you should be aware of because if you are considering migrating your system to GraphQL, this quirk will likely increase the time required to do so because you will have to change your error handling and any code that specifically checks for standard error codes. This will likely mean changing many of your test code as well.

10. A final consideration of GraphQL is the complexity of it. Now this isn’t really a disadvantage or an advantage. The reason being is that it isn’t particularly complex, however it is more complex than a standard REST API. If you know that your application is going to have a relatively simple and stable API over time, then you might be better sticking with REST. If you are unsure about this, I would be better to use GraphQL from the start as the complexity involved in migrating from REST to GraphQL once an application is midway through development wouldn’t be the quickest process, you’d have to define all your schemas, mutations, queries, and resolvers. Plus you’d potentially have to write new tests and learn a whole new testing API.