Sources

GraphQL didn’t go viral because devs were bored. It solved **real pain**. - **Overfetching/Underfetching**: REST gives you too much or too little. GraphQL gives you just what you asked for. - **Too Many Endpoints**: GraphQL says, "One endpoint to rule them all." - **Mobile-First**: For apps where bandwidth matters? GraphQL is lean and mean. - **Frontend Freedom**: React + GraphQL is like chai + biscuit. Tightly paired.

GraphQL is a great tool for developers overall, but of course there are a few pain points you might deal with during the development process. In this article, we'll break down some of the biggest pain points you might experience using GraphQL tools. Right off the bat, if you're developing an API that is super simple and doesn't need any complex functionality, then GraphQL tools might not be the best choice for you. Instead, it might make things more complicated than they need to be. You'll be better off sticking to the typical REST API tools. However, if you need something a bit more complex, then GraphQL will be perfect for what you need and it'll help you create a great API. Of course, making a simple API with GraphQL isn't impossible, just inconvenient. The following pain points, however, are super difficult to deal with and if you need these functionalities, GraphQL might not be your solution. GraphQL returns responses in the shape of the query, so if you need a specific structure, you'll have to program a transformation to make it return that way. GraphQL doesn't have infinite depth capabilities, so pagination will be necessary. Other pain points don't pose nearly impossible barriers, but they can still cause difficulties. Things like network level caching and file upload handling. Though it isn't impossible to find solutions for these issues, it will still add some time to development. All in all, GraphQL tools are exceedingly useful in a wide variety of API contexts, so whether or not you should use it just depends on your needs.

I’m talking about problems such as: - **Schema duplication** - **Server/client data mismatch** - **Superfluous database calls** - **Poor performance** - **Boilerplate overdose** I’m willing to bet your app suffers from at least one of them. Good news is, none of them are incurable! … ### Problem: Schema Duplication One of the first things you realize when coding a GraphQL back-end from scratch is that it involves a lot of similar-but-not-quite-identical code, especially when it comes to schemas. Namely, you need one schema for your database, and another one for your GraphQL endpoint. Not only is it frustrating to have to write more or less the same thing twice, but you now have two independent sources of truths that you need to constantly keep in sync. … ### Problem: Server/Client Data Mismatch As we’ve just seen, your database and GraphQL API will have different schemas, which translate into different document shapes. So while a `post` fresh out of the database will have a `userId` property, the same `post` as fetched through your API will instead have a `user` property. This means that getting a post author’s name on the client will look like: … This can be a problem anytime you’re trying to share code between client and server to simplify your codebase. And even beyond that, it means you’re missing out on GraphQL’s great approach to data querying on the server. I recently felt that pain when trying to build a system to generate weekly newsletters: each newsletter was composed of multiple posts and comments, along with info about their authors; in other words, a perfect use case for GraphQL. But this newsletter generation was happening on the *server*, meaning I didn’t have a way to query my GraphQL endpoint…But what about GraphQL? Assuming our posts have a `user` field with its own resolver, we still have one initial database call to get the list of posts. But we now have an extra call to fetch each user *per resolver*, for a total of **11** database calls! Now imagine that each post also has 5 comments, each of which has an author. Our number of calls has now ballooned to: … ### Problem: Poor Performance Even with Dataloader enabled, complex views can still trigger multiple database calls, which in turn can make for slow loading times. This can be frustrating: on one hand you want to take full advantage of GraphQL’s graph traversal features (“show me the authors of the comments of the author of the post of…” etc.). But on the other hand, you don’t want your app to become slow and unresponsive. … ### Problem: Boilerplate Overdose This is by no means an issue exclusive to GraphQL apps, but it’s true that they generally require you to write a lot of similar boilerplate code. Typically, adding a new model (e.g. `Comments`) to your app will involve the following steps:

### Complexity of Query Design One of the primary challenges faced by GraphQL developers is the complexity of query design. Unlike traditional RESTful APIs, which have predefined endpoints for specific data objects, GraphQL allows clients to specify exactly what data they need in a single query. While this flexibility is one of the key advantages of GraphQL, it also introduces complexity in terms of query design. … ### Schema Stitching and Composition Another common challenge faced by GraphQL developers is schema stitching and composition. In a typical GraphQL application, data is fetched from multiple sources, each with its own schema definition. Schema stitching involves combining these schemas into a single, coherent schema that can be queried by clients. Schema stitching can be a complex and time-consuming process, especially in applications with a large number of data sources. Developers must carefully map data relationships between schemas and ensure that the final stitched schema is consistent and well-structured. … ### Understanding the Challenges One of the main challenges faced by GraphQL web developers is performance optimization. GraphQL allows clients to request only the data they need, which can be a huge advantage in terms of reducing the amount of data transferred over the network. However, if not optimized correctly, this can lead to performance issues such as slow response times and increased server load. Another challenge is the complexity of GraphQL queries. With GraphQL, clients can request data from multiple sources in a single query, which can make it difficult to optimize performance. Developers need to carefully design their schemas and queries to ensure they are efficient and performant. … ### Data Fetching Challenges One of the key advantages of GraphQL is its ability to allow clients to request only the data they need, reducing over-fetching and under-fetching of data. However, this flexibility can also pose challenges for developers, especially when dealing with complex data structures. One common challenge faced by GraphQL developers is managing the complexity of data fetching queries. As applications grow in size and complexity, the number of queries needed to fetch all the required data can increase significantly. This can lead to performance issues, as each query requires a separate network round-trip to the server. … ## Comments (37) GraphQL can be a powerful tool for web developers, but it definitely comes with its fair share of challenges. One common issue is dealing with overly complex queries. Sometimes you end up with nested queries within nested queries, making it difficult to keep track of what data you're actually fetching.<code> query { user { posts { comments { user { posts { comments { // You get the idea... } } } } } } } </code> Another challenge is cache management. With traditional REST APIs, caching can be straightforward, but with GraphQL, it's a bit trickier to know when to refetch data and when to rely on the cache. Schema stitching can also be a headache. If you're working with multiple schemas from various services, stitching them together smoothly can be quite the task. And don't even get me started on testing. Writing tests for GraphQL queries and mutations can be a nightmare, especially when you have to mock out all the different data scenarios. Overall, GraphQL definitely has its benefits, but it's important to be aware of the challenges that come with it. One of the biggest challenges with GraphQL development is managing the schema. As your application grows, keeping track of all the types, queries, and mutations can get pretty messy. It's crucial to regularly review and update your schema to ensure everything aligns correctly. Mutation management is another tricky area. With GraphQL, mutations are used to make changes to your data, but it can be tough to handle the complexity of mutations that involve multiple entities and relationships. … But perhaps the biggest challenge of all is debugging. When something goes wrong with a GraphQL query, trying to track down the issue can feel like searching for a needle in a haystack. It's important to have solid logging and error tracking in place to make your life easier. And what about query complexity? How do you prevent users from running overly complex queries that could potentially bring down your server? Are there any best practices you follow to limit query depth or complexity? ... Alright, let's dive into some of the common challenges faced by GraphQL developers. One issue that often comes up is handling file uploads. Unlike with REST APIs, file uploads in GraphQL can be a bit trickier, requiring special handling on the server side. Then there's the challenge of data validation. With GraphQL, you have to define your own validation rules for incoming data, which can be a lot of extra work compared to some other frameworks that handle validation automatically. … It's all too easy to accidentally create queries that are too deep or too complex, leading to performance issues and potential bottlenecks in your application. And don't even get me started on caching. Managing the cache in a GraphQL environment can be a real headache, especially if you're working with data that changes frequently or unpredictably.

Another key aspect is the Schema Definition Language (SDL). This schema describes the types of data available and their relationships. It acts as a contract between the client and server, ensuring that both parties understand the data structure. Strong typing helps catch errors early, reducing the chances of runtime issues. However, with great power comes great responsibility. GraphQL's flexibility can lead to complex queries that may overwhelm servers. Developers must understand how their queries will be executed to avoid performance pitfalls. This complexity can be daunting, especially for newcomers. It’s like navigating a labyrinth; one wrong turn can lead to a dead end. … Despite its advantages, GraphQL is not without its drawbacks. The learning curve can be steep, especially for those accustomed to REST. Developers may find themselves grappling with the intricacies of crafting efficient queries. Moreover, the potential for over-fetching or under-fetching data remains a concern. It’s a balancing act, requiring careful consideration of how data is structured and accessed. … Another key aspect is the Schema Definition Language (SDL). ... GraphQL's flexibility can lead to complex queries that may overwhelm servers. Developers must understand how their queries will be executed to avoid performance pitfalls. This complexity can be daunting, especially for newcomers. It’s like navigating a labyrinth; one wrong turn can lead to a dead end. … Despite its advantages, GraphQL is not without its drawbacks. The learning curve can be steep, especially for those accustomed to REST. Developers may find themselves grappling with the intricacies of crafting efficient queries. Moreover, the potential for over-fetching or under-fetching data remains a concern. It’s a balancing act, requiring careful consideration of how data is structured and accessed.

When working with complex data operations, complications often arise. These hurdles can lead to significant delays and frustration. As technologies evolve, so do the intricacies of efficiently managing data interactions. Sometimes, even minor oversights can result in considerable setbacks in development timelines. It's essential to recognize the typical pitfalls encountered during these processes. Developers frequently grapple with validation errors, performance setbacks, and unintended data retrieval issues. Such challenges are not just nuisances; they can hinder project progress and affect overall system performance. … One frequent headache is handling variable types and their mismatches. For instance, a numeric variable mistakenly passed as a string can result in runtime errors. Additionally, the lack of proper validation on input data can lead to security vulnerabilities, allowing malicious users to exploit the system. Another prevalent concern is the efficiency of data retrieval. Developers may unintentionally request excessive data, resulting in performance degradation. On the contrary, requesting too little data can lead to multiple round trips to the server, further impacting application speed and responsiveness. … One major element to consider is the depth of nested queries. When queries are deep, the system might struggle to retrieve all necessary data in a timely manner. Additionally, requests that involve multiple related entities can significantly increase the load time. Developers need to strike a balance between the richness of the data and the speed of retrieval. … Yo, one common issue I see with GraphQL is not handling errors properly. Like, some devs forget to check for errors in their resolvers and end up returning null values instead of throwing an error. Remember to always throw an error when something goes wrong, so the client knows something's up. Bro, another issue is not optimizing queries. Some peeps make the mistake of fetching more data than needed, which can slow down the server and waste resources. Make sure to only request the data that's necessary for the client and avoid over-fetching. … So, I've seen some devs struggle with handling complex data structures in GraphQL. It can be a pain to map nested objects and arrays, especially when dealing with relations between types. Take your time to plan out your schema and resolvers properly to avoid headaches later on. Aight, a common pitfall is forgetting to properly handle authentication and authorization in GraphQL. Don't just trust that the client will always send valid credentials - make sure to authenticate and authorize requests on the server side to protect your data and APIs. Sup, peeps often forget to batch their queries in GraphQL, resulting in N+1 query problems. This can lead to slow performance and put unnecessary strain on your database. Use DataLoader or other batching techniques to optimize your queries and fetch data more efficiently. One issue that devs face is dealing with schema changes in GraphQL. If you're constantly updating your schema, it can be a pain to keep everything in sync. Consider using a tool like Apollo's schema stitching or schema delegation to manage schema evolution smoothly.

- Duplicated schemas - Mismatched server/client data - Inefficient queries and N+1 problems - Slow performance - Excessive boilerplate The good news is, smart architecture and modern tooling can overcome these hurdles. ... ## Problem 1: Duplicated Schemas One of the first challenges new GraphQL developers encounter is having to define their data schema in multiple places. You need one schema for your database models, and another similar-but-not-quite-identical schema for your GraphQL types. Keeping them in sync is tedious and error-prone. … ## Problem 2: Server/Client Data Mismatch Often the shape of your data will be different in your database vs. your GraphQL responses. For example, a blog post in the database might have an `authorId` field, while the GraphQL version has an `author` object: ``` // Post in database _id: ‘123‘, title: ‘Hello world‘, authorId: ‘456‘ // Post from GraphQL _id: ‘123‘, title: ‘Hello world‘, author: { _id: ‘456‘, name: ‘John Smith‘ ``` … ## Problem 3: Inefficient Queries and N+1 A common performance issue is "N+1 queries" – your server executes a separate database query for each child record, leading to an explosion in database calls. Consider a GraphQL query like this: ``` query Posts { posts { _id title comments { _id text author { _id name ``` … ## Problem 4: Poor Query Performance Even with the N+1 problem solved, some GraphQL queries are just expensive by nature. Queries with deep nested relationships, large result sets, or complex filtering can bog down your server and make for a poor user experience. … ## Problem 5: Too Much Boilerplate Our last problem isn‘t specific to GraphQL, but it‘s common in GraphQL apps. Exposing each entity in your data model requires a lot of repetitive code – a new type definition, new root query fields, new resolvers, new mutations, etc. For example, adding a

Such a finding indicates the increasing difficulty of the GraphQL domain in the GraphQL community. Sri et al. (Vadlamani et al., 2021) confirms such difficulty of GraphQL in their recent study, which surveyed 38 Github employees who expressed that GraphQL was challenging to learn, time-consuming with limited knowledge-base resources, especially when compared to mature protocols such as REST. … Additionally, implementing REST queries became more challenging with complex endpoints and multiple parameters. Participants without experience found GraphQL easier to implement and understand (Brito and Valente, 2020). Wittern et al.’s empirical investigation of over 8K GraphQL schemas mined from GitHub suggests that most APIs have security issues that can be exploited using complex queries (Wittern et al., 2019).

This quickly becomes burdensome when you add new resources to the application; however, this same burden is also a feature. The application is self-documenting and it's easy to understand the entrypoints into an application that's being exposed via HTTP/HTTPS. In a large, complex GraphQL applicaton tracking down how clients query the API requires more energy than you would like. There's a lot of engineering discipline required to keep your GraphQL API from turning itself into a REST-like API as a product changes. In the first GraphQL query above, … There are many cases where you might already have a piece of data available from a database query and you would like to "return early," as we've done here but GraphQL makes your pay a tax of sorts for the flexibility it offers. This tax, in large code bases, can grow and become cumbersome. The non-linear nature of dealing with graphs has left me wanting some sort of GUI representation of the graph that lights up as a request moves through each resolver. Was REST so bad that we need to make understanding how our requests are routed more difficult?

### Cons GraphQL can be harder to set up; its other disadvantages are below. - **Complexity in Caching**: Traditional caching mechanisms, like HTTP caching, are not as effective with GraphQL because of its dynamic queries. It often requires custom strategies like persisted queries and Apollo Client caching. - **Increased Server Load**: Due to the complexity of GraphQL queries, server performance can sometimes suffer. It’s essential to implement rate limiting and query depth control to avoid overload. - **Learning Curve**: Developers need to familiarize themselves with schema definitions, resolvers, and query structures, making it more challenging to learn than REST APIs. Debugging can also be more complex. - **Security Risks**: There’s the potential for clients to send expensive or deeply nested queries, risking denial-of-service (DoS) attacks. Proper query validation and authorization are crucial.

An opposite (but equally inefficient) problem is under-fetching. This is when the API call doesn’t fetch enough information, so it has to make one or more additional round trips to enrich its data and build the required data model. That’s a lot of wasted bandwidth and resources, not to mention added latency. Plus a lot of complexity for consumers who want to integrate with the API product. … ## OpenTelemetry and GraphQL performance issues There are plenty of use cases for GraphQL, as well as plenty of challenges. One added complexity is that each client can have a different performance profile on their per query basis, depending on how complex the query is. So, while one client could experience amazing performance, another could be facing performance problems. There’s also the N+1 challenge – a commonly recognised problem, where GraphQL’s execution of a separate resolver for each field in a query results in N+1 round trips to the database. OpenTelemetry can help. You can use it to detect N+1 queries. ... That way, you can be aware of these kinds of expensive queries much faster. Other issues that can affect GraphQL performance include cyclic queries (a potential vulnerability for GraphQL APIs, as they can be used for denial-of-service attacks) and very expensive queries (those with both greater depth in terms of nesting levels and with higher complexity). While OpenTelemetry can help with some of these issues, it’s not quite there yet with others – which is why Tyk is adding its voice to OpenTelemetry community discussions.

Similar to other API specifications, GraphQL should be paired with API management software to get the most benefits. GraphQL is often implemented as a gateway or middleware for different data sources, which means that the API performance and security depend on these downstream sources. To optimize GraphQL API performance, you should make use of a query cost analysis to implement rate limiting based on the connected data sources. Presentations at GraphQLConf discussed how observability and rate limiting play important roles in API management for GraphQL. ## 3. GraphQL security Security for GraphQL APIs is becoming even more critical now that enterprises have started running GraphQL at scale. As the structure of GraphQL is different from other API specifications, it has its own needs in terms of security. During the conference, GraphQL-specific vulnerabilities like complexity issues and schema leaks were highlighted. Of course, security threats that apply to standard API specifications—such as injections and server errors—also apply to GraphQL APIs and can often be mitigated by API management solutions.