What you need to know about GraphQl in 2024
Having worked with GraphQL for several years, the author wants to pass on his insights and experience with this technology.
GraphQL has grown into something of a big deal over the years. Plenty of developers got enthusiastic about this technology, me included.
Having worked with this technology for several years, I’d like to pass on my insights and experience with GraphQL.
Let’s begin with a basic definition: what is GraphQL?
GraphQL is a query language that allows you to specify which data you get back in response to a request. It also offers a runtime that resolves those queries against your existing data. You can think of that data as nodes in a graph. Objects can be related to other objects, yet you may only care about a small subset of those nodes.
Easy enough? Great, let’s dig deeper.
Freedom
GraphQL lets the service’s clients freely choose what they get back from the server. For every request – whether a query, a mutation or a subscription – you decide which information to retrieve and which fields you don’t need. These are the only 3 request types. Query operations are meant for reading data, Mutation operations for changing it, and Subscription operations deliver real-time updates whenever new data appears.
As a client, you can ask for all the data you need in one query. If only certain parts of the data interest you, you can ask for just those. Different parts of your system/UI can select different data.
This means the API provider doesn’t have to anticipate every edge case of how the data will be used. That works really well when your public API has many clients, since they can consume your data in many different ways.
This idea has a considerable impact on our development process. Teams, or parts of teams such as the backend and the frontend, can communicate more asynchronously. The reason is that there is a contract between the provider and the consumer – a schema, which we’ll cover later.
By its nature, GraphQL links data objects together. So when we add a field to an object, every query response returning that object type can now include an extra field. There’s no need to ask the backend team to add a single field to every endpoint.
Adding a new field to the schema doesn’t require notifying all of the schema’s clients, since they won’t be using that data. Then again, perhaps you should if you work together as a Team.
Does that mean the backend developer will build a huge schema and leave the rest to the clients? Certainly not. There are plenty of cases where some requests need to be optimized for fetching more data or for filtering it.
This freedom of choice can also shrink your payload considerably. For instance, in Migrating to GraphQL: A Practical Assessment – where the authors moved the GitHub API from REST to GraphQL – the payload went down from 93.5 fields (median values) to just 5.5 after the move to GraphQL. As a result, the response size fell from 9.8 MB (median values) to only 86 KB after switching to GraphQL. That’s excellent news for mobile applications sharing an API with web applications.
This is exactly why GraphQL was created in the first place. Here is Facebook’s earliest article about it.
Schema
I’ve brought up the schema. It is, in a way, the place where developers can agree on what queries/subscriptions and mutations will look like. To me, it is one of GraphQL’s greatest features. Creating it is unavoidable. And even if it weren’t, you shouldn’t skip it, because it gives you control over the development process and establishes a contract between the API provider and its clients – whether that’s a front-end teammate, a team on another continent or even an outside company.
The GraphQL schema is strongly typed, so tools can help us verify whether a request matches the schema. The GraphQL server validates requests as well. Providers rely on the schema to build correct entry points into the service.
The schema has a hierarchical structure, which means certain fields can be nested (custom types). This lets you avoid multiple requests to the service, particularly when fetching data centered on a single node/aggregate. Still, you won’t always be able to traverse the graph and collect everything. Some nodes aren’t connected in the GraphQL schema. In such cases, we can handle it by running more than one operation in a single request.
There are a few ways to give clients the schema. You can share a file with them, or a client can fetch the schema with an introspection query. Disabling introspection queries on your production service is good practice.
This article explains why and how to do it.
The schema frequently takes a load off our shoulders when we would otherwise wonder What endpoint should I query for this use case? That’s no longer my concern – GraphQL gives me a schema, and if the information is in it, I can fetch it.
Code Generation
Since GraphQL gives us a schema to work with, tools can generate structures for use in code, on both the Backend and the Frontend. This simple capability spares you the tedious creation/editing of classes every time the schema changes. In Java, for example, you can use graphql-java-codegen. This can be especially handy in bigger projects where we don’t know about every change in the schema. We simply pull the latest version of the schema, rebuild the code, and everything is up-to-date. It also protects us from trivial mistakes like typos in field names. Code generation will most likely save you some time.
Evolution
GraphQL is described as version free, meaning that if you do things right, there’s no need to version your schema.
Applications released by Facebook over three years are still supported on one and the same version of our GraphQL API.
GraphQL – a data query language
How can that possibly work?
Adding a new field doesn’t break any contract – the client doesn’t even have to know those new fields or queries exist, right?
Fine, but what about removing features? This is where the @Deprecated directive saves the day.
First, let’s explain what a directive is**.**
Put as simply as possible, it’s an extra piece of information you can include in the schema. You can also build logic around directives, which makes them pretty powerful.
Now, back to @Deprecated.
Using the @Deprecated directive
It signals to clients that this part of the schema should no longer be used. However, the field stays in our schema even after being marked with @Deprecated, and over the years we may accumulate quite a few of them. That’s why we should keep an eye on how our schema is being used. Once you’re sure that no one uses the field anymore, you can remove it.
Observability deserves a blog post of its own, but you might want to check out Apollo Studio, which lets you view statistics on your schema, requests, failure rate and much more, helping you judge whether a field can be removed.
Evolving a GraphQL schema is a gradual process rather than a big-bang change.
Naturally, if you’re in a small team or communicate well with your clients, you can drop a field once both sides are ready, without keeping long-lived @Deprecated fields. As always, it all depends.
Inefficient Queries
GraphQL offers us plenty of freedom and possibilities, but, as usual, nothing comes for free. Most objects in our schema are connected, which can lead to some developers wanting to fetch all the data. On top of that, some data may be nested, and we could fetch that too.
So what’s the problem? The data is in the schema, so why can’t I just pull it?
From GraphQL’s perspective, each field is a function. Often this resolver method is very simple – just a getter on the object. Backend tools frequently hide this from us, since we only deal with objects. Some fields, however, are different: they require computing something or sending an extra request to another service simply because that data lives elsewhere. It’s difficult to tell which fields are expensive.
For instance:
Example User node
Can we easily tell which of these fields need extra requests? Probably accountNumber, right? But perhaps name and lastName need some obfuscation for security reasons. Or perhaps there won’t be any extra requests or computations at all. We can never be certain what happens after we make our call. This example is very simple, with only four fields. What if we had 20 fields with custom nested types? It would get much harder.
What follows from this?
N+1 problem
Example of a potential N+1 Problem
We might add a new field to our User holding all of a given User’s credit cards. Every time we fetch a User, we could fetch the user’s cards as well. Here, the server would want to fetch each element of that collection separately, which could lead to an N+1 problem.
Issues like this can be addressed with data loaders. It’s an extra fetching mechanism that lets your server batch nodes and request them all at once.
Dependency hell
Another potential problem is that fetching entire objects can trigger many requests to numerous services just to retrieve one GraphQL object. But is the client to blame for wanting a field such as an account number? Of course not. So how do we tackle this?
I’ve seen developers lean towards godly types in Schemas. Over the course of development, for example, our User type could turn into a monster like this:
Example of a huge node
Fetching an entire User object would be painful, wouldn’t it? Many of these fields are fairly complex and may require an extra query to some service. Occasionally, getting certain fields might even mean sending a request to an external source of truth (such as government servers).
Most likely, no view needs all that information. So what can we change? We can alter the data structure underneath (database or services) or the schema on top.
Where possible, steer clear of changing the database schema. Tight coupling between the API and the database is something you want to avoid. One option is to move data from one service to another. That might work, but keep in mind that services have responsibilities beyond collecting data – they handle scalability, business logic, bounded contexts and so on.
Another option is to build a read model for this specific type. This can work nicely, though you may run into eventual consistency issues on reads.
The last resort is changing the GraphQL schema.
Basing your schema on the UI isn’t a good idea. Instead, we can borrow concepts from domain-driven design, especially ubiquitous language. By definition, it is a set of terms shared by the business and development teams, which both should understand in the same way.
So let’s try breaking our User up into a few separate concepts.
(If you work in the banking domain, you’ll probably find my naming silly – apologies for that :) )
This split follows several distinct contexts that could give rise to separate apps or views for various kinds of users. The people who grant you a mortgage are most likely not the same people who get in touch with you about credit cards.
Moreover, each type of information may come from a different place. SecurityInformation, for instance, holds information on whether clients have been hacked. That sort of data doesn’t belong to the debt domain, does it?
At this point, many of these types aren’t connected. If the split is done well, that’s a good thing. Each query will now simply fetch information from a single place (service/read-model) as quickly as possible.
Can this be achieved in production? Most likely not – you’ll probably still have connections between types, as in MortgageInfromation. Your aim, though, should be to reduce how many there are.
Is the data source the best and only criterion for splitting objects in the schema? It’s a good one, but we also need to keep read rights in mind.
What I can see?
Every time we handle a request from a user, we have to verify who that user is and whether they have the right permissions to fetch certain data. Let’s look at our Account type now.
Suppose the loans field can only be fetched by a handful of user types. What should happen when a user fetching the entire object lacks access to that field? Should we throw an exception? That seems right, since something went wrong on the server side. There’s also another approach: returning a partial object. All fields would then be available, but what value would the loans field hold? We could return null, but the “!” in the schema says the field will never be null. So perhaps we should return an empty list?
It’s a small yet significant decision, since it could introduce inconsistency into our application. Some clients might now get an empty list of loans even though loans exist. Your user might make a business decision based on that data. Not great, is it?
Perhaps if I have access to the Account type, I should be able to fetch every field? Permissions would then sit on the root type of the query. It’s an interesting approach that makes the authorization problem simpler.
Naturally, there’s a price: doing this may make API design feel constrained. As the domain changes, we could still end up in the same situation. A custom directive can help your API consumers. We discussed the @Deprecated directive, but you can also write your own custom one. You might, for example, create a directive called @hasRole that takes the required role and then checks at runtime whether the user has it.
Example of a custom directive
Security
Is GraphQL secure? As usual, the answer ought to be “It depends”. But I bet you’re tired of hearing that. So let me rephrase the question: “Will my app be secure if I simply addGraphQL to the stack?” In that case, the answer is no. As so often happens, when we give users a lot of freedom, they may use it to hurt you. A frequent mistake is leaving the introspection query enabled in production, which lets users of our product fetch queries and data they should never see. In such a scenario, custom directives such as @hasRole reveal a great deal to potential attackers.
This is an important topic to explore in depth, and it deserves an article of its own. Don’t overlook it, because it could do your production a lot of damage.
That said, if you want to learn about GraphQL vulnerabilities in a safe setting, I strongly recommend the Damn Vulnerable GraphQL Application project. It’s a hack me application packed with vulnerabilities to exploit. Enjoy :)
GraphQL implementations
Bear in mind that not every GraphQL server implementation necessarily supports every feature.
Why? The GraphQL specification was written in 2015, and its most recent official update came in 2021. Our industry is constantly evolving, so certain decisions had to be made.
Take, for instance, the question of which HTTP response status to return. You might assume 200, and indeed, 200 OK is “common practice”, but the GraphQL spec doesn’t say anywhere which code the server should return. Consequently, some tools use different codes for errors.
Graphlq-helix or Netlix-dgs take a different approach to this.
Some developers find this problematic, which is why they wrote an RFC (still a draft) describing how GraphQL should be served and consumed over HTTP.
The differences go beyond status codes. Some implementations handle security differently or even add extra types. It’s worth keeping that in mind.
Summary
GraphQL is a fantastic technology that’s worth exploring. I suggest experimenting with it, or simply checking out Apollo’s free tutorials. It may give you a new perspective on APIs and the development process.
Keep in mind that even when something looks amazing from the outside, you should examine its potential cost more closely before using it in production. Good Luck.