What is GraphQL and why is it so good?

GraphQL provides a flexible and efficient way to query and manipulate data, as opposed to traditional REST APIs with a set structure and limitations in data retrieval. With GraphQL, the client has more control over the data it receives and can request exactly what it needs without over or under-fetching. This can result in faster and more efficient applications. Like REST, GraphQL can be used by any platform e.g. native mobile app, web, desktop app, etc.

Here are some of the main selling points of GraphQL. Many of these addresses pain points seen in the REST world:

1. Flexibility: GraphQL allows the client to specify exactly what data it needs, reducing the amount of over- or under-fetching data compared to traditional REST APIs. It is easier to fetch the data required for a specific use case, leading to faster and more efficient applications.
2. Performance: GraphQL can often result in fewer round trips to the server than REST APIs, as all the required data can be requested in a single request. It can lead to improved performance, especially in low-bandwidth or high-latency environments.
3. Type System: GraphQL has a built-in type system that allows you to define the structure of your data, making it easier to validate user input and ensure that your API is always in a consistent state.
4. Easy to use: GraphQL provides a simple yet powerful syntax for querying and manipulating data, making it easy for developers to start using it immediately.
5. Better documentation: The GraphQL schema acts as documentation for your API, making it easier for other developers to understand how to use your API correctly.

GraphQL isn't a REST replacement

There are many direct comparisons between GraphQL and REST. While it is good to have those discussions to understand the role of GraphQL in an organisation, the comparison is inaccurate at best. Because GraphQL isn't here to replace REST. Instead, it works best when acting as the interfacing layer that sits in front of REST.

I have worked on projects where the architecture looks like the following diagram:

We had GraphQL services that talked directly to SQL databases. It sounds great in theory but a nightmare in practice. We wrote SQL queries in GraphQL resolvers without help from the typical ORM database tools. It could have been a better dev experience and error-prone. The team did its best to refactor things and apply abstractions to reduce code logic duplications, but it didn't work. It was still hard to understand and messy. Not to mention testing anything is incredibly difficult.

GraphQL offers the most value when it doesn't have to worry about the business logic and focuses on what it does best: distributing requests and aggregating results. Of course, it doesn't mean we shouldn't have business logic in GraphQL, but based on my experience, the less logic the better.

I recommend that anyone thinking about adopting GraphQL or working on a new green field project consider the following architecture.

PS: there are SaSS services out there which can make generating some of the CRUD operations from the database easier. This might be attractive for small projects or startups. Still, it will be best for the business to leave these SaSS services and build out the REST layer internally for better control and support those customisations needed as part of the business growth journey.

GraphQL doesn't make getting your product out faster

GraphQL can be misconceiving when it comes to development time because it is perfect at some things and gives the wrong impression that it will always speed up your project.

If you agree with what I talked about in the previous section, the first elephant in the room is that adopting GraphQL means building up one additional service and layer in your architecture. This translates to more development work, both in terms of writing the schema and resolvers. On the DevOps side, there are deployment pipelines, infrastructure setup, monitoring and alerting, security, etc. All of this can take more time than implementing the GraphQL service itself.

As mentioned already, to build and use GraphQL effectively, the development team must have a deep understanding of GraphQL and consider security and performance implications. Wrong design decisions or choices could lead to more development time spent on rectifying these mistakes.

Who's best suited to adopt GraphQL?

GraphQL shines when it is used in medium or large companies with many APIs and client teams. Since GraphQL provides a single entry point for all the APIs client teams need. The added benefits of reduced over and under-fetching could improve client-side performance massively on low-end devices or customers with poor internet connections.

Introducing GraphQL is easy, but the coordination needed to make GraphQL work well in an organisation is the real test. If not careful, it will cause more overhead and delays than it was intended to improve. Schema changes become a massive talking point because it impacts everyone, both the client teams consuming from GraphQL and the underlying API teams providing data to it. Small companies or startups don't benefit enough from GraphQL to justify the cost it brings. Typically speed and release quickly is the main driver for companies that those stages, and adopting something like tRPC might be a better choice. Of course, it is always possible to migrate to GraphQL later as a replacement (or even build on top of it?) at a later point.

For medium-sized companies, who are already starting to see innovation slowdowns caused by an increasing number of REST APIs or hearing complaints from client teams about the backend, it might be time to start investing in GraphQL. There are so many benefits that come with GraphQL when done right.

GraphQL would still be a massive help for large companies, but there might be limits to what it can solve at the scale. Instead of adopting a monolith GraphQL service, they should look at more scalable options such as schema-stitching with GraphQL Mesh or schema federation with Apollo Federation. We'll get into it at another time 🙂