What is the N+1 problem in GraphQL and why is it worse than in REST?

The N+1 problem occurs when a GraphQL query for a list of items (N items) triggers an additional database query for each item to resolve a nested field — resulting in N+1 queries total. It is more pronounced in GraphQL because field resolvers fire independently for each item in a list; the resolver for User.posts runs once per user, unaware that it will be called 100 times for 100 users. In REST, the endpoint developer typically writes a JOIN that fetches related data in one query. In GraphQL, you must explicitly add DataLoader to batch those individual loads into a single query. Without DataLoader, a query for 100 users with their posts becomes 101 database queries instead of 2.

How does cursor-based pagination work in GraphQL (Relay connection spec)?

The Relay connection specification defines the cursor-based pagination pattern most GraphQL APIs follow. A paginated field returns a Connection type containing edges (each with a node and cursor) and pageInfo (hasNextPage, endCursor). To get the next page, the client sends the endCursor as the after argument on the next query. The server translates this cursor (usually a Base64-encoded ID or timestamp) into a SQL WHERE clause (e.g., WHERE created_at < cursor_timestamp ORDER BY created_at DESC LIMIT n). This approach is stable when new data is inserted — unlike offset pagination where page 2 results can shift as new items are added to page 1.

Should I use a union type or an interface for GraphQL error handling?

The modern GraphQL error handling best practice uses union result types (also called the "result type pattern") rather than top-level GraphQL errors. Define each mutation result as a union: union CreatePostResult = Post | ValidationError | AuthorizationError. The client queries __typename to determine which type was returned and handles each case explicitly. This is superior to throwing GraphQLErrors because: error cases are explicit in the schema (clients know what errors to expect), partial success is representable, type-checking tools can enforce exhaustive handling, and the GraphQL response still returns 200 OK with a typed error in data (not in the errors array). Use the errors array only for unexpected server errors and infrastructure issues.

What are persisted queries and why do they improve security?

Persisted queries (also called automatic persisted queries or APQ) pre-register a set of allowed GraphQL operations on the server by their SHA-256 hash. Clients send only the hash, not the full query string. The server looks up the operation and executes it. Benefits: (1) Security — attackers cannot send arbitrary queries; only pre-registered operations execute. This prevents abusive queries from flooding your resolvers. (2) Bandwidth — the client sends a 64-character hash instead of a potentially large query string. (3) GET-cacheable requests — hash-identified queries can be made via GET and cached at the CDN layer, one of GraphQL's biggest caching weaknesses. Apollo Client and Apollo Server support APQ out of the box with client-side fallback to full query on cache miss.

How do I prevent abusive GraphQL queries from overloading my server?

GraphQL's flexible query language allows clients to send deeply nested or very complex queries that can overwhelm your resolvers. Protections: (1) Query depth limiting — reject queries nested beyond a maximum depth (e.g., 7 levels). Use graphql-depth-limit. (2) Query complexity analysis — assign a cost to each field, reject queries above a total complexity threshold. Use graphql-query-complexity. (3) Persisted queries — only allow pre-registered operations (see previous question). (4) Rate limiting — limit requests per authenticated user per minute at the API gateway layer. (5) Field-level timeouts — use Promise.race with a timeout in resolvers that call external services. (6) Pagination limits — cap the maximum limit/first argument on paginated connections (e.g., max 100 items per page) to prevent fetching huge datasets in one query.

Engineering·10 min read·June 21, 2026

🔗 GraphQL API Design Best Practices

Q: Should I use a union type or an interface for GraphQL error handling?

The modern GraphQL error handling best practice uses union result types (also called the "result type pattern") rather than top-level GraphQL errors. Define each mutation result as a union: union CreatePostResult = Post | ValidationError | AuthorizationError. The client queries __typename to determine which type was returned and handles each case explicitly. This is superior to throwing GraphQLErrors because: error cases are explicit in the schema (clients know what errors to expect), partial success is representable, type-checking tools can enforce exhaustive handling, and the GraphQL response still returns 200 OK with a typed error in data (not in the errors array). Use the errors array only for unexpected server errors and infrastructure issues.

Q: What are persisted queries and why do they improve security?

Persisted queries (also called automatic persisted queries or APQ) pre-register a set of allowed GraphQL operations on the server by their SHA-256 hash. Clients send only the hash, not the full query string. The server looks up the operation and executes it. Benefits: (1) Security — attackers cannot send arbitrary queries; only pre-registered operations execute. This prevents abusive queries from flooding your resolvers. (2) Bandwidth — the client sends a 64-character hash instead of a potentially large query string. (3) GET-cacheable requests — hash-identified queries can be made via GET and cached at the CDN layer, one of GraphQL's biggest caching weaknesses. Apollo Client and Apollo Server support APQ out of the box with client-side fallback to full query on cache miss.

Q: How do I prevent abusive GraphQL queries from overloading my server?

GraphQL's flexible query language allows clients to send deeply nested or very complex queries that can overwhelm your resolvers. Protections: (1) Query depth limiting — reject queries nested beyond a maximum depth (e.g., 7 levels). Use graphql-depth-limit. (2) Query complexity analysis — assign a cost to each field, reject queries above a total complexity threshold. Use graphql-query-complexity. (3) Persisted queries — only allow pre-registered operations (see previous question). (4) Rate limiting — limit requests per authenticated user per minute at the API gateway layer. (5) Field-level timeouts — use Promise.race with a timeout in resolvers that call external services. (6) Pagination limits — cap the maximum limit/first argument on paginated connections (e.g., max 100 items per page) to prevent fetching huge datasets in one query.

A comprehensive guide to GraphQL API design: schema design for types, queries, mutations, and subscriptions — solving the N+1 problem with DataLoader, cursor-based pagination, authentication via context, error handling, persisted queries, and GraphQL vs REST trade-offs.

📖Full-Stack SaaS with Next.js, Supabase & Groq AI (Full Access)

View →

Why GraphQL Exists and When to Choose It

GraphQL was created by Facebook (Meta) to solve a specific problem at mobile scale: REST APIs returned too much data (over-fetching) or required multiple round-trips (under-fetching). With GraphQL, the client specifies exactly which fields it needs in a single query. This is compelling for mobile apps and complex UIs, but GraphQL introduces its own complexity — particularly around caching, security, and the N+1 problem. Understanding the trade-offs before committing is essential.

Topics covered

GraphQL API designGraphQL schema designGraphQL DataLoader N+1GraphQL paginationGraphQL mutations subscriptionsGraphQL authentication contextGraphQL error handlingGraphQL vs REST trade-offspersisted queries GraphQLGraphQL cursor paginationApollo Server GraphQLGraphQL type systemGraphQL fragmentsGraphQL batching DataLoaderGraphQL federationGraphQL code-first schema-firstGraphQL subscriptions WebSocketGraphQL complexity limiting