GraphQL at Scale

Real-World Story: GitHub’s API Evolution. In 2016, GitHub announced they were building their next-generation API on GraphQL. Their REST API (v3) had been one of the most widely used public APIs in the world, but the team had hit a wall. Mobile clients were making dozens of REST calls to render a single screen. Third-party integrations were over-fetching massive payloads just to read two fields. Adding new fields to REST endpoints risked breaking thousands of integrations. The GitHub engineering team evaluated the cost of maintaining two paradigms and decided GraphQL was worth the investment. By 2017, GitHub’s GraphQL API (v4) was public. It let clients request exactly the data they needed in a single round trip. The schema became living documentation — every field, type, and relationship was introspectable. But the migration was not free: GitHub had to build custom query complexity analysis to prevent abuse, implement persisted queries for performance, and educate an entire developer ecosystem on a new paradigm. Today, GitHub’s GraphQL API handles billions of requests per month, and their experience — the wins and the scars — is the best case study for what it actually takes to run GraphQL at scale.

Real-World Story: Shopify’s GraphQL-First Architecture. Shopify runs one of the largest GraphQL APIs in the world, serving over 2 million merchants and their storefronts. When they adopted GraphQL, the team discovered that the real challenge was not the technology itself — it was organizational. Who owns which part of the schema? How do you prevent one team’s schema changes from breaking another team’s queries? How do you rate-limit a query language where every request has a different cost? Shopify solved this by building a calculated query cost system: every field in their schema has a cost weight, and each API call is charged against a cost budget rather than a simple request count. A query requesting 250 products with variants and images costs more than a query requesting a single shop name. This approach — which they open-sourced and documented extensively — became the blueprint for how the industry thinks about GraphQL rate limiting. The lesson: the hardest GraphQL problems at scale are not about resolvers and schemas. They are about governance, security, and operational visibility.

1. GraphQL Fundamentals (Quick Recap)

GraphQL is a query language for APIs and a runtime for executing those queries against your data. Unlike REST, where the server decides the shape of the response, in GraphQL the client describes exactly what it needs and the server returns precisely that — no more, no less.

Schema-First vs Code-First Design

There are two philosophical approaches to building a GraphQL API: Schema-first (SDL-first): You write the schema definition language (SDL) file first, then implement resolvers that match it. The schema is the contract, the source of truth. Teams discuss and review the schema before writing any code. This is how Apollo Server, GraphQL Yoga, and most mature teams work.

type Product {
  id: ID!
  name: String!
  price: Float!
  reviews: [Review!]!
}

type Query {
  product(id: ID!): Product
  products(first: Int, after: String): ProductConnection!
}

Code-first: You write resolver code and the schema is generated from it. Libraries like Nexus (TypeScript), Strawberry (Python), and gqlgen (Go) take this approach. The advantage is type safety — your schema cannot drift from your implementation because they are the same artifact. Which to choose: Schema-first is better for cross-team collaboration and API-first design (you can share the schema before any code exists). Code-first is better for solo developers or teams where the backend owns the schema entirely and wants compile-time guarantees. Most large organizations doing federation end up schema-first because the schema is the contract between teams.

Queries, Mutations, Subscriptions

Queries read data. They are the GET of GraphQL. Multiple queries in one request are resolved in parallel.
Mutations write data. They are the POST/PUT/DELETE of GraphQL. Multiple mutations in one request are executed sequentially (this is by spec, to avoid race conditions).
Subscriptions push real-time data to clients over a persistent connection (typically WebSocket). The client subscribes to an event, and the server pushes updates as they occur.

The Type System

GraphQL’s type system is its superpower. Every field has a type, every type is documented, and the schema is introspectable at runtime.

Scalars: String, Int, Float, Boolean, ID — plus custom scalars like DateTime, JSON, URL
Objects: The core building block. A named type with fields.
Enums: A fixed set of values (enum OrderStatus { PENDING, SHIPPED, DELIVERED, CANCELLED })
Unions: “This field returns one of these types” — useful for search results or feeds that contain mixed content
Interfaces: Shared fields across types — interface Node { id: ID! } is the Relay convention
Input types: Special object types used exclusively for arguments to mutations and queries

Resolvers and the Execution Model

A resolver is a function that returns the data for a single field. The GraphQL execution engine walks the query tree top-down, calling resolvers for each field. This is elegant but has a critical implication: each field is resolved independently, which means nested fields can trigger separate database queries — the infamous N+1 problem (covered in depth below).

const resolvers = {
  Query: {
    product: (_, { id }) => db.products.findById(id),
  },
  Product: {
    reviews: (product) => db.reviews.findByProductId(product.id),
    // This runs once per product -- if you queried 50 products,
    // this resolver fires 50 times, each hitting the database
  },
};

When GraphQL Wins Over REST (and When It Doesn’t)

GraphQL wins when: You have multiple client types (web, mobile, watch, third-party) with different data needs. Your frontend is evolving rapidly and waiting for backend API changes is a bottleneck. Your data is graph-shaped with deep relationships. You are building a public API where consumers want flexibility.

REST wins when: You have a simple CRUD API. Your data is flat and resource-oriented. You need aggressive HTTP caching (REST’s biggest free advantage). You are building server-to-server APIs where both sides are controlled. Your team is small and the overhead of a GraphQL schema is not justified. You need file uploads as a primary use case.

2. The N+1 Problem in GraphQL

This is the single most common performance issue in GraphQL APIs, and understanding it deeply is a prerequisite for any serious GraphQL work.

How It Manifests

Consider this query:

query {
  products(first: 50) {
    name
    reviews {
      rating
      comment
    }
  }
}

The execution engine resolves products first — one database query returning 50 products. Then, for each of those 50 products, it calls the reviews resolver. That is 50 separate database queries. Total: 1 + 50 = 51 queries for what should be a single JOIN. At scale, this destroys your database. The N+1 problem is not a GraphQL bug — it is a consequence of the field-level resolver model. REST APIs avoid it because the server controls the response shape and can write optimized queries. GraphQL gives control to the client, so the server must compensate. For deeper coverage of database query optimization, indexing strategies, and EXPLAIN analysis that apply when diagnosing slow resolvers, see APIs and Databases and Database Deep Dives.

The DataLoader Pattern

Facebook invented the DataLoader pattern to solve exactly this. The idea is beautifully simple: batch and deduplicate database calls within a single request. Instead of each resolver immediately hitting the database, it tells the DataLoader “I need reviews for product ID 42.” The DataLoader collects all such requests during a single tick of the event loop, then fires one batched query:

// Without DataLoader: 50 queries
SELECT * FROM reviews WHERE product_id = 1;
SELECT * FROM reviews WHERE product_id = 2;
// ... 48 more

// With DataLoader: 1 query
SELECT * FROM reviews WHERE product_id IN (1, 2, 3, ..., 50);

Implementation: Facebook’s DataLoader Library

const DataLoader = require('dataloader');

// The batch function receives an array of keys
// and must return results in the same order
const reviewLoader = new DataLoader(async (productIds) => {
  const reviews = await db.reviews.findByProductIds(productIds);
  // Group reviews by product ID
  const reviewMap = {};
  reviews.forEach(r => {
    if (!reviewMap[r.productId]) reviewMap[r.productId] = [];
    reviewMap[r.productId].push(r);
  });
  // Return in the same order as the input keys
  return productIds.map(id => reviewMap[id] || []);
});

// Resolver now uses the loader
const resolvers = {
  Product: {
    reviews: (product) => reviewLoader.load(product.id),
  },
};

Critical: DataLoaders must be created per-request, not globally. A DataLoader caches results for the lifetime of the instance. If you reuse a DataLoader across requests, user A might see user B’s data because the cache still holds the previous request’s results. Create a fresh DataLoader instance in your request context for every incoming GraphQL operation.

Per-Request Batching vs Cross-Request Caching

DataLoader solves within a single request. It batches all calls made during one query’s execution into a single database call, and it deduplicates (if two fields request the same product ID, only one database call is made). For cross-request caching (the same product being requested by different users), you need an external cache layer — Redis, Memcached, or an in-memory LRU cache in front of your DataLoader. Some teams compose these: DataLoader for per-request batching, Redis for cross-request caching, and the DataLoader’s batch function checks Redis before hitting the database.

Monitoring N+1 Issues in Production

You cannot fix what you cannot see. Instrument your GraphQL server to:

Enable query tracing — Apollo Server’s tracing plugin reports per-resolver execution time
Count database queries per request — If a single GraphQL operation triggers 100+ database queries, you have an N+1 problem
Use APM tools — Datadog, New Relic, and Sentry all have GraphQL-specific instrumentation that shows resolver-level performance
Log slow resolvers — Set a threshold (e.g., 50ms) and log any resolver that exceeds it, including which field and what parent type

Practical rule of thumb: A well-optimized GraphQL query should execute roughly O(depth) database queries, not O(nodes). If your query has 3 levels of nesting but triggers 200 database calls, something is wrong with your data loading strategy.

3. Query Complexity and Security

A public GraphQL API is an open invitation for abuse unless you actively defend it. Unlike REST, where each endpoint has a predictable cost, a single GraphQL query can range from trivial to catastrophic.

Query Depth Limiting

The simplest attack: deeply nested queries that exploit circular relationships.

# Malicious query: exponential depth
query {
  user(id: "1") {
    friends {
      friends {
        friends {
          friends {
            friends {
              # ... 20 levels deep
            }
          }
        }
      }
    }
  }
}

Solution: Set a maximum query depth (typically 7-12 levels for most APIs). Libraries like graphql-depth-limit reject queries that exceed the threshold before execution begins. This is your first line of defense — cheap and effective.

Query Complexity Analysis

Depth limiting is crude. A shallow query can still be expensive if it requests large lists at every level. Query complexity analysis assigns a cost to each field and rejects queries whose total cost exceeds a budget.

// Assign costs to fields
type Query {
  products(first: Int): [Product!]! @cost(complexity: 1, multiplier: "first")
}

type Product {
  reviews: [Review!]! @cost(complexity: 2)
  relatedProducts: [Product!]! @cost(complexity: 3)
}

A query requesting 100 products, each with reviews and 10 related products, might have a calculated cost of 100 * (1 + 2 + 3 * 10) = 3300. If your budget is 1000, this query is rejected with a helpful error message explaining the cost breakdown. Shopify’s approach: They expose the calculated cost in the response extensions so clients can see how much “budget” each query consumes and optimize accordingly.

Persisted Queries / Allowlisting

The most secure approach for production APIs where you control the clients: only allow queries you have pre-approved.

During development, the build process extracts all GraphQL operations from your frontend code
Each operation is hashed (SHA-256) and registered with the server
In production, clients send only the hash, not the full query text
The server looks up the hash and executes the registered query

This eliminates arbitrary query attacks entirely. If it is not in the allowlist, it does not run. Apollo Server supports this via Automatic Persisted Queries (APQ), and Relay’s compiler generates persisted queries by default.

Trade-off: Persisted queries eliminate flexibility — you cannot use GraphiQL or ad-hoc queries in production. This is fine for your own clients but not for a public API where third-party developers need to write their own queries. For public APIs, use complexity analysis and depth limiting instead.

Rate Limiting by Query Cost

Traditional REST rate limiting counts requests: “100 requests per minute.” This is meaningless for GraphQL because one request can be trivial or devastating. Cost-based rate limiting assigns a budget per time window based on query complexity:

Simple query ({ me { name } }) — cost 1
Medium query (product listing with pagination) — cost 50
Complex query (deep relationships, large lists) — cost 500
Budget: 1000 cost units per minute

This is how Shopify, GitHub, and most mature GraphQL APIs rate-limit. GitHub’s API returns rateLimit data in every response so clients can track their remaining budget.

Introspection in Production

GraphQL introspection lets anyone query your schema’s structure — every type, every field, every argument. This is invaluable during development but dangerous in production for several reasons:

Attackers can map your entire data model
Internal fields you forgot to hide are exposed
It makes crafting malicious queries much easier

Recommendation: Disable introspection in production for private/internal APIs. For public APIs, you may keep it enabled (GitHub does) but combine it with robust complexity analysis. At minimum, gate introspection behind authentication.

Injection Attacks Through Variables

GraphQL variables are typed, which provides some protection against injection. But developers still make mistakes. For broader coverage of injection attacks, the OWASP Top 10, and defense-in-depth security principles, see the Auth and Security chapter.

// DANGEROUS: String interpolation in resolvers
const resolvers = {
  Query: {
    search: (_, { term }) => {
      // SQL injection via the GraphQL variable
      return db.raw(`SELECT * FROM products WHERE name LIKE '%${term}%'`);
    },
  },
};

Always use parameterized queries in your resolvers. GraphQL’s type system validates the shape and type of variables, but it does not sanitize string content. The resolver layer must handle that.

The security checklist for production GraphQL:

Depth limiting (7-12 levels)
Query complexity analysis with cost budgets
Persisted queries if you control all clients
Cost-based rate limiting
Disable or gate introspection
Parameterized queries in all resolvers
Authentication and authorization on every resolver (not just the root)
Request timeout (kill queries that run too long — 30 seconds is generous)

4. Federation (Distributed GraphQL)

Federation is how you scale GraphQL organizationally — from one team owning one monolithic schema to multiple teams each owning a piece of a unified graph.

What Federation Solves

Imagine an e-commerce company with separate teams for Products, Orders, Reviews, and Users. Without federation, either:

One team owns the entire schema — that team becomes a bottleneck. Every frontend request requires them to add fields.
Each team has its own GraphQL API — the frontend must know which team owns which data and stitch queries together manually.

Federation gives you a third option: each team owns their subgraph (their piece of the schema), and a gateway automatically composes them into a single unified graph (the supergraph). The frontend sends one query to one endpoint, unaware that the data comes from four different services.

Apollo Federation v2

Apollo Federation is the dominant standard for federated GraphQL. Here are the key concepts: Entities are types that can be referenced and extended across subgraphs. Any type with a @key directive is an entity:

# Products subgraph
type Product @key(fields: "id") {
  id: ID!
  name: String!
  price: Float!
}

# Reviews subgraph -- extends Product
type Product @key(fields: "id") {
  id: ID!
  reviews: [Review!]!
}

@key defines the primary key used to fetch an entity across subgraphs. Multiple keys are supported. @external marks a field as being defined in another subgraph — you reference it but do not own it. @requires indicates that a field needs data from an external field to resolve:

# Shipping subgraph
type Product @key(fields: "id") {
  id: ID!
  weight: Float @external
  shippingCost: Float @requires(fields: "weight")
  # To calculate shippingCost, the gateway must first
  # fetch weight from the Products subgraph
}

Schema Composition and the Supergraph

The supergraph is the composed schema that represents the union of all subgraphs. Apollo’s composition process:

Each team publishes their subgraph schema to a schema registry (Apollo Studio, or self-hosted with Rover CLI)
The composition engine validates that subgraphs are compatible (no conflicting type definitions, all entity references are resolvable)
If composition succeeds, it produces a supergraph schema that the gateway uses to plan queries

Schema composition catches errors before deployment. If the Reviews team adds a Product.rating field that conflicts with a field the Products team already defined, composition fails and the deployment is blocked. This is the federated equivalent of a compile error — it is far better to catch conflicts at build time than in production.

Entity Resolution Across Subgraphs

When a query spans multiple subgraphs, the gateway orchestrates entity resolution:

Client sends: { product(id: "42") { name price reviews { rating } } }
Gateway’s query planner sees that name and price live in the Products subgraph, reviews lives in the Reviews subgraph
Gateway fetches { product(id: "42") { name price } } from the Products subgraph
Gateway calls the Reviews subgraph’s _entities resolver with { __typename: "Product", id: "42" } to get reviews
Gateway merges the results and returns the unified response to the client

The _entities query is the backbone of federation. Every subgraph that defines entities must implement this resolver, which takes a list of entity representations (typename + key fields) and returns the corresponding objects.

Federation vs Schema Stitching

Schema stitching (the pre-federation approach) required the gateway to manually define how to merge schemas, which types to delegate, and how to resolve cross-service references. It was brittle, centralized, and did not scale organizationally because every cross-service change required gateway updates. Federation inverts the model: subgraphs declare their own relationships, and composition is automatic. The gateway does not need custom configuration — it reads the composed supergraph and plans queries automatically. Federation won because it decentralizes ownership. Teams can evolve their subgraphs independently, publish changes through a CI pipeline, and the gateway adapts without manual intervention.

Federated Gateway Performance

The gateway introduces an extra network hop and must plan how to orchestrate queries across subgraphs. Two key concerns: Query planning overhead: The gateway’s query planner analyzes each incoming query and produces an execution plan (which subgraphs to call, in what order, what data to pass between them). For complex queries spanning many subgraphs, planning can take milliseconds. Apollo Router (the Rust-based gateway) is significantly faster than the Node.js-based Apollo Gateway for this reason. For more on gateway architecture patterns, routing, and the role of gateways in microservice communication, see API Gateways and Service Mesh. The waterfall problem: If resolving field B requires data from field A (which lives in a different subgraph), the gateway must call subgraph A first, wait for the response, then call subgraph B. Multiple sequential dependencies create a waterfall of requests. Designing your schema to minimize cross-subgraph dependencies is the most effective optimization.

Organizational patterns for federation: Assign subgraph ownership by domain, not by team size. The team that owns the Order domain owns the Orders subgraph. Establish a schema governance process — a schema review board or automated linting in CI — to ensure consistency across subgraphs (naming conventions, pagination patterns, error handling).

5. Performance Optimization

For foundational performance concepts — latency vs throughput, connection pooling, async processing, and backpressure patterns — see the Performance and Scalability chapter. This section covers GraphQL-specific performance patterns that build on those foundations.

Response Caching Strategies

GraphQL’s biggest caching challenge: every query is a POST with a unique body, so traditional HTTP caching (CDN, browser cache) does not work out of the box. Persisted queries + CDN caching: When using persisted queries, each operation has a stable hash. You can use GET requests with the hash as a query parameter (/graphql?extensions={"persistedQuery":{"sha256Hash":"abc123"}}), which makes the request cacheable by CDNs. This is the closest you get to REST-style HTTP caching with GraphQL. Automatic Persisted Queries (APQ): A protocol where the client first sends only the hash. If the server recognizes it, it executes. If not, the client resends the full query, and the server registers it for future requests. This saves bandwidth on repeated queries without requiring a build-time registration step. Server-side response caching: Cache full responses keyed by the operation hash + variables. Apollo Server’s @cacheControl directive lets you set max-age per field, and the server calculates the overall cache policy as the minimum across all requested fields.

@defer and @stream — Progressive Delivery

These directives let the server send partial responses incrementally:

query {
  product(id: "42") {
    name
    price
    ... @defer {
      reviews {
        rating
        comment
      }
    }
  }
}

The server returns name and price immediately, then streams reviews as a subsequent chunk when they are ready. This is transformative for user experience: the client can render the product details while reviews are still loading, without making a second request. @stream does the same for lists — items are delivered as they resolve rather than waiting for the entire array.

Pagination: Cursor-Based (Relay Spec) vs Offset

Offset-based (products(offset: 20, limit: 10)) is simple but breaks at scale: inserting or deleting items shifts pages, and OFFSET in SQL becomes slower as the offset grows (the database still scans all skipped rows). Cursor-based (Relay Connection spec) uses an opaque cursor (typically a base64-encoded ID or timestamp) that points to a position in the dataset:

type ProductConnection {
  edges: [ProductEdge!]!
  pageInfo: PageInfo!
}

type ProductEdge {
  cursor: String!
  node: Product!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}

Cursor-based pagination is consistent regardless of concurrent inserts/deletes, and the database query uses WHERE id > cursor LIMIT 10 which is index-friendly and fast at any depth. Recommendation: Use cursor-based pagination for any list that could grow beyond a few hundred items. The Relay Connection spec is verbose but well-understood across the industry and supported by tooling.

Subscriptions Architecture

Subscriptions maintain a persistent connection (typically WebSocket via graphql-ws protocol) between client and server. For a deep dive into WebSocket internals, connection lifecycle, scaling persistent connections, and alternatives like Server-Sent Events, see the Real-Time Systems chapter. Architecture considerations at scale:

WebSocket connections are stateful — they must be pinned to a specific server instance. This complicates horizontal scaling because you cannot simply round-robin load balance.
Pub/Sub backend: Use Redis Pub/Sub, Kafka, or a similar system to broadcast events to all server instances. When a mutation triggers an event, publish it to the pub/sub system. Every server instance with active subscriptions for that event pushes the update to its connected clients.
Filtering: Not every subscriber cares about every event. Filter at the server level (not the client) to avoid sending unnecessary data. For example, only push order updates to the user who owns the order.

Subscriptions at scale are expensive. Each active subscription holds an open WebSocket connection, consuming memory and file descriptors on the server. 100,000 concurrent subscribers is 100,000 open connections. Consider whether polling (every 5-10 seconds) or Server-Sent Events (SSE) might serve your use case with less operational complexity. Many teams start with subscriptions and migrate to polling when they realize the infrastructure cost is not justified by the latency improvement.

Schema Design for Performance

Avoid deep nesting by default. Every level of nesting is a potential resolver call and a potential waterfall in federation. If Product -> Reviews -> Author -> Products -> Reviews is queryable, someone will query it.
Denormalize strategically. Add computed or denormalized fields to avoid multi-hop resolution. A Product.averageRating field that reads from a precomputed column is cheaper than having the client query all reviews and calculate the average.
Use pagination everywhere. Never return unbounded lists. Even if today a product has 5 reviews, tomorrow it might have 5,000.

6. GraphQL in Production

Monitoring

Field-level monitoring is what separates production-grade GraphQL from a side project. Operation-level metrics: Track latency, error rate, and request volume per named operation (e.g., GetProductPage, SearchProducts). This is equivalent to per-endpoint metrics in REST. Field-level metrics: Track how often each field is requested and how long it takes to resolve. This data is critical for schema evolution — before deprecating a field, you need to know if anyone is using it. Error rates by operation: GraphQL always returns HTTP 200, even when there are errors (they go in the errors array). Your monitoring must parse GraphQL responses to detect application-level errors. A 200 status code with "errors": [{ "message": "Not authorized" }] is not a successful request.

Tools for GraphQL monitoring: Apollo Studio provides operation-level and field-level analytics out of the box. For self-hosted solutions, integrate with Prometheus by exporting custom metrics from your GraphQL middleware (operation name, latency, error count per field). Grafana dashboards should show: operations per minute, P50/P99 latency by operation, error rate by operation, and the slowest resolvers.

Schema Evolution

GraphQL schemas should evolve additively. The rules:

Safe changes: Adding new fields, new types, new arguments with default values, new enum values (with caution — clients using exhaustive switch statements may break)
Dangerous changes: Making a nullable field non-nullable, removing enum values
Breaking changes: Removing fields, removing types, changing a field’s type

Deprecation flow:

Mark the field with @deprecated(reason: "Use newField instead")
Monitor field usage via field-level analytics
When usage drops to zero (or an acceptable threshold), remove in a future version
Breaking change detection tools (Apollo’s rover CLI, GraphQL Inspector) can run in CI to catch unintentional breaking changes

Client-Side Libraries

Library	Philosophy	Best For	Trade-offs
Apollo Client	Feature-rich, normalized cache	Most production apps	Larger bundle, complex cache management
Relay	Compiler-driven, colocated fragments	Facebook-scale apps with strict patterns	Steep learning curve, opinionated
urql	Lightweight, extensible	Simpler apps, teams wanting less magic	Fewer built-in features than Apollo
TanStack Query + graphql-request	Use what you know	Teams already using TanStack Query	No normalized cache, manual invalidation

My recommendation: Apollo Client for most teams — its normalized cache and dev tools are worth the complexity. Relay if you are at a scale where its compiler-driven approach pays off (100+ engineers, thousands of components). urql if you want something lighter and your caching needs are simple.

Code Generation

graphql-codegen generates TypeScript types, React hooks, and SDK code from your schema and operations. It eliminates an entire class of bugs — you cannot reference a field that does not exist in the schema because the types will not compile. Relay Compiler goes further: it analyzes your queries at build time, generates optimized runtime artifacts, and produces persisted queries automatically. It is the most sophisticated GraphQL build tool but requires buying into Relay’s entire ecosystem.

Testing GraphQL APIs

Operation-level integration tests: Send real GraphQL operations to a test server with a seeded database. Assert on the response shape and data.
Schema snapshot tests: Detect unintentional schema changes by committing a snapshot of the schema and failing CI when it changes without an explicit update.
Resolver unit tests: Test individual resolvers with mocked data sources. Useful for complex business logic but less valuable than integration tests for catching N+1 issues and authorization bugs.
Contract tests: If you use federation, test that each subgraph’s schema composes successfully with the supergraph before deployment.

For broader testing strategy (the testing pyramid, integration vs unit test balance, CI pipeline design), see Testing, Logging, and Versioning.

7. GraphQL vs REST — The Real Trade-offs

This is the question that comes up in every architecture discussion, and the honest answer is: it depends. Here is the nuanced breakdown.

When to Choose GraphQL

Multiple clients with different data needs. If your web app, mobile app, and third-party integrations all need different subsets of the same data, GraphQL eliminates over-fetching and the need for custom endpoints.
Rapidly evolving frontend. When the frontend team is iterating faster than the backend team can create new REST endpoints, GraphQL lets the frontend get exactly the data it needs without backend changes.
Complex, interconnected data. If your data model is a graph (users have friends who have posts that have comments by users who have…), GraphQL’s query language maps naturally to this structure.
Strong typing and self-documentation. The schema serves as a living contract and documentation. GraphiQL and Apollo Explorer let developers explore the API without reading docs.

When to Stick with REST

Simple CRUD operations. If your API is “create, read, update, delete resources” with flat data, REST is simpler and better supported by tooling, caching, and infrastructure.
Server-to-server communication. Between backend services, you control both sides. gRPC is usually a better choice than either REST or GraphQL for this.
Caching is critical. REST’s GET requests are natively cacheable by CDNs, browsers, and proxies. GraphQL requires extra work (persisted queries, cache-control directives) to achieve comparable caching. See the Caching and Observability chapter for the foundational caching patterns (write-through, cache-aside, TTL-based invalidation) that underpin GraphQL caching strategies.
File uploads. GraphQL does not have a native file upload story. The graphql-upload package exists but it is a workaround. REST (or dedicated upload endpoints) is simpler.

Hybrid Approach

Many companies run both: REST for their public API (third-party developers expect REST, tooling is better, caching is simpler) and GraphQL for their frontend (flexibility, no over-fetching, rapid iteration). This is not a compromise — it is a pragmatic recognition that different consumers have different needs.

Migration Strategies: REST to GraphQL Gateway

If you have an existing REST API and want to add GraphQL:

GraphQL as a gateway layer — build a GraphQL API that delegates to your existing REST endpoints in its resolvers. The frontend gets GraphQL; the backend stays REST. This is the lowest-risk migration path.
Incremental migration — start with one domain (e.g., product catalog) in GraphQL, keep everything else in REST. Migrate domain by domain based on where GraphQL adds the most value.
Strangler fig pattern — new features are built in GraphQL, existing features stay in REST until they are naturally rewritten.

Airbnb’s approach: Airbnb built a GraphQL gateway that wrapped their existing REST services. Frontend teams could query the GraphQL API for the data they needed, while backend teams continued to evolve their REST services independently. Over time, some services migrated their data sources directly into GraphQL resolvers, but the gateway approach let them start getting value immediately without a risky big-bang rewrite.

8. GraphQL Error Handling

GraphQL’s error model is fundamentally different from REST’s, and most teams get it wrong in their first implementation. In REST, you return an HTTP status code (404, 500, 403) and the client interprets it. In GraphQL, the server almost always returns HTTP 200, and errors are communicated in a structured errors array alongside partial data. This is not a bug — it is a deliberate design decision that enables partial responses, but it requires a different error-handling mindset.

The GraphQL Error Specification

Every GraphQL response has this shape:

{
  "data": { ... },
  "errors": [ ... ],
  "extensions": { ... }
}

data is always present (it may be null if the entire operation fails). It contains whatever data the server could successfully resolve.
errors is an array of error objects, each with a message, locations (where in the query the error occurred), and path (which field failed).
extensions is an optional bag for metadata — tracing data, cost information, error codes, and anything else the server wants to communicate.

The critical insight: GraphQL supports partial responses. If your query requests a product’s name, price, and reviews, and the reviews resolver fails, the server returns the name and price successfully with a null for reviews and an error in the errors array. The client gets useful data and an error signal. REST has no equivalent — it is all or nothing.

Error Types and When to Use Each

1. GraphQL execution errors (resolver errors): These are errors thrown during field resolution. The field returns null, and an entry appears in the errors array. Use for: database timeouts, service unavailability, unexpected failures.

{
  "data": {
    "product": {
      "name": "Widget",
      "price": 29.99,
      "reviews": null
    }
  },
  "errors": [
    {
      "message": "Failed to fetch reviews",
      "locations": [{ "line": 5, "column": 5 }],
      "path": ["product", "reviews"],
      "extensions": {
        "code": "DOWNSTREAM_SERVICE_ERROR",
        "serviceName": "reviews-service"
      }
    }
  ]
}

2. Validation errors (pre-execution): The query itself is malformed — syntax errors, unknown fields, wrong argument types. The GraphQL engine rejects these before any resolver runs. data is null. 3. User errors (business logic errors returned in the payload): Validation failures, permission issues, “item out of stock” — these are not system errors, they are expected outcomes. The best practice is to return these in the mutation payload, not in the top-level errors array.

type CreateReviewPayload {
  review: Review
  errors: [UserError!]!
}

type UserError {
  field: String        # Which input field caused the error
  message: String!     # Human-readable message
  code: ErrorCode!     # Machine-readable code for client logic
}

enum ErrorCode {
  VALIDATION_FAILED
  NOT_AUTHORIZED
  NOT_FOUND
  RATE_LIMITED
  CONFLICT
}

This pattern (used by Shopify, GitHub, and most mature GraphQL APIs) keeps the top-level errors array clean for unexpected failures and gives clients structured, predictable error information for expected failures.

Error Extensions for Rich Error Metadata

The extensions field on each error object is where you put machine-readable information that clients can act on programmatically:

{
  "message": "Rate limit exceeded",
  "extensions": {
    "code": "RATE_LIMITED",
    "retryAfter": 30,
    "costRequested": 1500,
    "costRemaining": 200,
    "documentation": "https://docs.api.example.com/rate-limits"
  }
}

Standardize your error codes. Define an enum of error codes (AUTHENTICATION_REQUIRED, FORBIDDEN, NOT_FOUND, RATE_LIMITED, INTERNAL_ERROR, VALIDATION_FAILED) and use them consistently across your API. Clients can switch on the code rather than parsing error message strings, which is brittle.

Apollo Server convention: Apollo Server uses extensions.code by default (UNAUTHENTICATED, FORBIDDEN, BAD_USER_INPUT, INTERNAL_SERVER_ERROR). If you are using Apollo, follow this convention. If you are building your own, model your codes similarly — they should be UPPER_SNAKE_CASE, stable (never renamed), and documented.

Client-Side Error Handling Patterns

Pattern 1: The error classification layer. Build a middleware that classifies errors before your UI components see them:

function classifyError(error: GraphQLError): ErrorClassification {
  const code = error.extensions?.code;
  switch (code) {
    case 'UNAUTHENTICATED':
      return { type: 'auth', action: 'redirect-to-login' };
    case 'FORBIDDEN':
      return { type: 'auth', action: 'show-permission-denied' };
    case 'RATE_LIMITED':
      return { type: 'transient', action: 'retry-after', delay: error.extensions?.retryAfter };
    case 'INTERNAL_SERVER_ERROR':
      return { type: 'system', action: 'show-generic-error' };
    default:
      return { type: 'unknown', action: 'log-and-show-generic' };
  }
}

Pattern 2: Partial data rendering. Since GraphQL returns partial responses, design your UI components to handle null fields gracefully. A product card that receives name and price but null for reviews should render the product information and show a “Reviews unavailable” placeholder — not crash or show nothing. Pattern 3: Mutation error handling with union types. For mutations where you need to distinguish success from different failure modes, use union return types:

union PlaceOrderResult = OrderSuccess | OutOfStockError | PaymentDeclinedError | ValidationErrors

type OrderSuccess {
  order: Order!
}

type OutOfStockError {
  productId: ID!
  availableQuantity: Int!
}

type PaymentDeclinedError {
  reason: String!
  retryable: Boolean!
}

This approach (sometimes called the “Result type” pattern) makes error states explicit in the schema, type-safe, and impossible for clients to ignore — the client must handle each variant because the type system requires it.

The HTTP 200 monitoring trap. Because GraphQL always returns 200, your HTTP monitoring will show a 100% success rate even when your API is failing constantly. You must parse GraphQL responses in your monitoring layer to detect application-level errors. Configure your APM tool (Datadog, New Relic) or your logging pipeline to inspect the errors array and report GraphQL errors as actual failures. See the Caching and Observability chapter for how to build observability pipelines that understand application-level error signals beyond HTTP status codes.

9. Migrating from REST to GraphQL — The Complete Playbook

The migration question comes up in nearly every GraphQL architecture discussion. Section 7 introduced three strategies (gateway, incremental, strangler fig). This section is the step-by-step operational playbook for actually executing the migration.

Phase 0: Validate That GraphQL Is the Right Move

Before writing a single line of GraphQL code, answer these questions:

Are multiple clients requesting different shapes of the same data? If your web app and mobile app both consume the same REST endpoints but only use 30% of the fields, GraphQL will eliminate significant over-fetching. If you have one client and one backend, GraphQL adds complexity without proportional benefit.
Is the frontend bottlenecked on backend API changes? If the frontend team files tickets to add fields to REST endpoints and waits sprints for delivery, GraphQL lets them self-serve. If backend deploys are already fast and collaborative, the organizational benefit is smaller.
Is your data graph-shaped? If your domain has deep relationships (users -> orders -> items -> reviews -> authors -> other-reviews), GraphQL’s nested query model is a natural fit. If your API is flat CRUD operations, REST is simpler.

If the answer to at least two of these is “yes,” proceed.

Phase 1: The Gateway Layer (Weeks 1-4)

Build a GraphQL server that sits in front of your existing REST API. Resolvers delegate to REST endpoints — no business logic moves yet.

// The GraphQL layer is a thin translation layer over REST
const resolvers = {
  Query: {
    product: async (_, { id }, { dataSources }) => {
      return dataSources.productAPI.getProduct(id);
    },
    products: async (_, { first, after, category }, { dataSources }) => {
      return dataSources.productAPI.listProducts({ first, after, category });
    },
  },
  Product: {
    reviews: async (product, _, { dataSources }) => {
      return dataSources.reviewAPI.getReviewsForProduct(product.id);
    },
  },
};

// RESTDataSource handles caching, deduplication, and error handling
class ProductAPI extends RESTDataSource {
  baseURL = 'http://product-service/api/v1/';

  async getProduct(id) {
    return this.get(`products/${id}`);
  }

  async listProducts({ first, after, category }) {
    return this.get('products', { params: { limit: first, cursor: after, category } });
  }
}

Key decisions in Phase 1:

Schema design: Do not mirror your REST API 1:1. Design the schema for how the frontend wants to consume data, not how the backend happens to structure it. This is your chance to fix API ergonomics.
Field mapping: REST responses may use snake_case; your GraphQL schema should use camelCase (the GraphQL convention). Map in the resolver or data source layer.
Authentication passthrough: Forward the client’s auth token to the REST endpoints. The GraphQL layer should not re-implement authentication initially — let the downstream REST services handle it. See Auth and Security for how to evolve this later.
Error mapping: REST errors (404, 500, 403) must be translated to GraphQL error conventions. A REST 404 becomes a null return with no error (the item simply does not exist). A REST 403 becomes a GraphQL error with extensions.code: "FORBIDDEN". A REST 500 becomes a GraphQL error with extensions.code: "INTERNAL_SERVER_ERROR".

Phase 2: Client Migration (Weeks 4-12)

Migrate frontend clients to consume the GraphQL API instead of REST. Do this screen by screen, not all at once.

Start with the highest-value screen. Pick the page that makes the most REST calls or suffers the most from over-fetching. For an e-commerce app, this is often the product detail page (product data + reviews + related products + inventory status — currently 4-6 REST calls, now 1 GraphQL query).
Run both APIs in parallel. The frontend can consume some data from GraphQL and some from REST during the transition. Use feature flags to control which data source each screen uses.
Measure the wins. Track: number of API calls per page load, total bytes transferred, time to first meaningful paint. These metrics justify the migration to stakeholders.
Generate TypeScript types from the schema. Use graphql-codegen to generate types and React hooks from your GraphQL operations. This eliminates the manual type definitions you maintained for REST responses and catches schema drift at compile time.

Phase 3: Resolver Optimization (Weeks 8-16, overlapping with Phase 2)

Once clients are consuming GraphQL, optimize the resolver layer:

Add DataLoaders for every resolver that fetches related data. Without them, your GraphQL gateway fires more REST calls than the frontend used to make directly.
Migrate high-traffic resolvers from REST delegation to direct data access. The product resolver can query the database directly instead of going through the REST endpoint. This eliminates a network hop and lets you write optimized queries (e.g., batch loading with WHERE id IN (...)).
Add caching. Use @cacheControl directives for response caching. Use Redis for cross-request caching of frequently accessed entities. See Caching and Observability for cache invalidation strategies.

Phase 4: REST Deprecation (Weeks 16+)

Monitor REST endpoint usage. Track which endpoints still receive traffic and from which clients.
Deprecate endpoints that are fully replaced by GraphQL. Announce deprecation, set a sunset date, and monitor.
Keep REST for legitimate use cases. Server-to-server communication, public developer APIs where REST is expected, webhook payloads, and file uploads are all cases where REST may remain the better choice. GraphQL does not have to replace everything.

The Coexistence Period

The reality: most organizations run REST and GraphQL in parallel for months or years. This is fine. The key rules during coexistence:

Single source of truth for each data domain. If the Products service is the source of truth for product data, both the REST endpoint and the GraphQL resolver should read from the same database or service. Do not create a second source of truth.
Avoid GraphQL-to-REST-to-GraphQL chains. If Service A exposes GraphQL, and Service B exposes REST, and Service A’s resolver calls Service B’s REST endpoint, that is fine. But if Service B then calls Service A’s GraphQL endpoint in a resolver, you have a circular dependency that will cause latency and debugging nightmares.
Unified authentication. Both the REST API and the GraphQL API should use the same auth mechanism (same JWTs, same token validation). Do not create separate auth flows. See Auth and Security for patterns.

How the API gateway fits in: During migration, your API gateway (Kong, Envoy, AWS API Gateway) can route traffic based on path: /graphql goes to the GraphQL server, /api/v1/* goes to the existing REST services. The gateway handles cross-cutting concerns (rate limiting, auth, TLS) for both APIs, giving you a single entry point and consistent security enforcement regardless of which API paradigm serves the request.

10. GraphQL Tooling Ecosystem

The tooling around GraphQL has matured significantly. Understanding what is available — and when each tool earns its place — is as important as understanding the runtime itself.

Apollo Studio (Apollo GraphOS)

Apollo Studio (now part of Apollo GraphOS) is the most comprehensive managed platform for GraphQL. What it provides:

Schema registry — the central source of truth for your supergraph schema. Teams publish subgraph schemas here. Composition happens here. This is where you see whether a schema change breaks compatibility.
Operation-level analytics — every named operation is tracked with latency percentiles, error rates, and request volume. You can see which operations are the slowest, which are most popular, and which are failing.
Field-level usage tracking — how often each field is requested, by which operations, and by which clients. This is essential for deprecation: you cannot safely remove a field unless you know who is using it. This data directly feeds the schema evolution workflow described in Section 6.
Schema change validation — when a subgraph publishes a schema update, Apollo Studio checks it against recent operation traffic. If the change would break a query that clients sent in the last 90 days, it flags it as a breaking change. This is a massive safety net for federation.
Trace inspection — drill into individual operations to see per-resolver timing, which subgraphs were called, and where time was spent. The federated query plan is visualized so you can see waterfall dependencies.

When to use it: If you are running Apollo Federation in production with multiple teams, Apollo Studio (or its self-hosted equivalent via Rover CLI) is close to essential. The schema registry and composition validation alone justify the cost for organizations with 3+ subgraphs. For smaller teams or non-federated setups, the free tier provides operation analytics that are still valuable. Alternative: GraphQL Hive by The Guild is an open-source schema registry and analytics platform. It is a credible alternative if you want to self-host or avoid vendor lock-in.

GraphQL Inspector — Breaking Change Detection

GraphQL Inspector is an open-source tool that compares two versions of a schema and detects breaking changes, dangerous changes, and safe changes. How it works in CI:

# GitHub Actions workflow
name: Schema Check
on: pull_request
jobs:
  schema-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Check for breaking changes
        uses: kamilkisiela/graphql-inspector@master
        with:
          schema: 'main:schema.graphql'  # Base branch schema
          # Compares against the schema in the current PR

What it detects:

Breaking: Removed field, removed type, changed field type, removed enum value, required argument added without default
Dangerous: Optional argument added, enum value added (may break exhaustive client switches), nullable field became non-nullable
Safe: New field, new type, new optional argument with default, deprecated field

Why this matters: Without automated breaking change detection, schema evolution is a manual code review process where reviewers must mentally diff the schema and reason about client impact. GraphQL Inspector automates this. It is the GraphQL equivalent of a type checker — it catches an entire class of errors before they reach production. Integration with Apollo: Apollo’s rover CLI provides similar functionality (rover subgraph check). If you are in the Apollo ecosystem, use rover. If you want an open-source, vendor-neutral option, GraphQL Inspector is the standard.

graphql-codegen — End-to-End Type Safety

graphql-codegen by The Guild generates TypeScript types, React hooks, Angular services, Vue composables, and more from your GraphQL schema and operations. The problem it solves: Without codegen, you write a GraphQL query in a string, then manually define TypeScript types for the response. This creates two sources of truth that drift apart. Codegen eliminates this: you write the query, run the generator, and get types that exactly match the schema. Setup:

# codegen.yml
schema: http://localhost:4000/graphql  # Or a local .graphql file
documents: src/**/*.graphql             # Your query/mutation files
generates:
  src/generated/graphql.ts:
    plugins:
      - typescript                      # Base types from schema
      - typescript-operations           # Types for specific operations
      - typescript-react-apollo         # React hooks for each operation

What it generates:

// Generated -- do not edit
export type Product = {
  __typename?: 'Product';
  id: string;
  name: string;
  price: number;
  reviews: ReviewConnection;
};

// Generated hook for a specific query
export function useGetProductQuery(
  baseOptions: Apollo.QueryHookOptions<GetProductQuery, GetProductQueryVariables>
) {
  return Apollo.useQuery<GetProductQuery, GetProductQueryVariables>(
    GetProductDocument,
    baseOptions
  );
}

// Usage in a component -- fully typed, no manual type definitions
const { data, loading, error } = useGetProductQuery({
  variables: { id: '42' },
});
// data.product.name is typed as string
// data.product.reviews is typed as ReviewConnection
// data.product.nonExistentField is a compile error

Why this is transformative: Every field reference in your frontend code is validated against the schema at compile time. Rename a field in the schema, run codegen, and the compiler tells you every component that needs updating. This eliminates an entire class of runtime errors — the “field was renamed and nobody told the frontend” bug. Advanced usage:

Fragment colocation: Write GraphQL fragments next to the components that use them. Codegen generates types per fragment, so each component gets exactly the types it needs.
Persisted query generation: Codegen can hash your operations and output a persisted query manifest for APQ.
Custom scalars mapping: Map GraphQL custom scalars (DateTime, Money, JSON) to TypeScript types so they are not all any.

Relay Compiler

The Relay Compiler is Facebook’s build-time GraphQL tool. It is not a general-purpose codegen tool — it is the compiler for the Relay client library. What makes it different:

Ahead-of-time optimization: The compiler analyzes all fragments and queries at build time, deduplicates fields, and produces optimized runtime artifacts. The client never parses GraphQL strings at runtime.
Persisted queries by default: Every operation is hashed at build time. In production, only hashes are sent.
Fragment validation: The compiler enforces that fragments only spread on compatible types and that data dependencies are satisfied. This catches bugs that other tools miss.

When to use it: Only if you are using Relay as your client. It is not a standalone tool. But if you are evaluating Relay, the compiler is its biggest advantage — it provides guarantees that no other GraphQL client can match.

Additional Tooling Worth Knowing

Tool	Purpose	When to use
GraphiQL / Apollo Explorer	Interactive query IDE in the browser	Development and debugging. Disable or gate in production for security (see Section 3).
Rover CLI	Apollo’s CLI for schema management	Federation: publish subgraphs, run composition checks, validate schema changes in CI.
graphql-eslint	ESLint rules for GraphQL operations	Enforce naming conventions, prevent deprecated field usage, require operation names.
graphql-ws	WebSocket protocol implementation	The standard WebSocket transport for GraphQL subscriptions. Replaces the deprecated `subscriptions-transport-ws`.
GraphQL Mesh	Unify non-GraphQL data sources into a GraphQL schema	When you want a GraphQL layer over REST, gRPC, SOAP, or database sources without writing resolvers manually.
WunderGraph	GraphQL-to-API gateway with caching and auth	When you want a BFF (Backend for Frontend) layer with built-in caching and security.

The minimum viable tooling stack for a production GraphQL API:

graphql-codegen for type safety between schema and frontend (free, open-source)
GraphQL Inspector or Rover CLI for breaking change detection in CI (free for Inspector, free tier for Rover)
DataLoader for N+1 prevention (free, open-source)
graphql-depth-limit + a complexity analysis library for security (free, open-source)
Apollo Studio free tier or GraphQL Hive for operation analytics

You can ship a production GraphQL API with zero vendor lock-in using entirely open-source tooling. Apollo Studio and GraphOS add significant value for federated architectures, but they are not required.

Interview Questions

Your GraphQL API is slow. How do you diagnose and fix it?

What they are really testing: Systematic debugging methodology for a technology where traditional tools (HTTP status codes, endpoint-level metrics) do not apply. They want to see if you understand GraphQL-specific performance characteristics.Strong answer:I would approach this in layers, from broadest signal to narrowest:1. Operation-level analysis. Start with APM data (Apollo Studio, Datadog) to identify which operations are slow. GraphQL’s “one endpoint” model means you cannot look at URL-level latency — you need operation-name-level metrics. Sort by P99 latency and error rate.2. Resolver-level tracing. Enable Apollo tracing or OpenTelemetry instrumentation on your GraphQL server. This shows per-resolver execution time within a single operation. Often, 90% of the latency is in one or two resolvers.3. Check for N+1 problems. The most common cause. Count database queries per operation. If a query with 50 items in a list triggers 50+ database calls, you have an N+1 problem. Fix with DataLoader — batch and deduplicate calls within the request lifecycle.4. Analyze query complexity. Some operations are genuinely expensive — requesting 1000 items with 5 levels of nesting. Add query complexity analysis to reject or warn on expensive queries. Review whether clients are over-fetching.5. Database layer. If resolvers are slow even with DataLoader, the issue is downstream: missing indexes, expensive JOINs, table scans. Run EXPLAIN on the generated SQL. Add indexes for common access patterns.6. Caching. Add response caching for operations that are read-heavy and do not need real-time data. Use @cacheControl directives for field-level cache policies. Consider CDN caching with persisted queries.7. Federation-specific issues. If using federation, the gateway’s query plan might involve sequential subgraph calls (waterfall). Review the query plan, consider denormalizing fields to reduce cross-subgraph hops, or use @requires judiciously.The key insight is that GraphQL performance debugging requires field-level and operation-level visibility, not just endpoint-level. Traditional REST monitoring is blind to GraphQL performance issues.

Explain how Apollo Federation works and when you would use it.

What they are really testing: Do you understand distributed GraphQL architectures and the organizational problems they solve, not just the technical mechanics?Strong answer:Apollo Federation is a specification and runtime for composing multiple GraphQL APIs (subgraphs) into a single unified API (supergraph), served through a gateway.The problem it solves: As organizations grow, having one team own the entire GraphQL schema becomes a bottleneck. Every frontend feature request requires that team to add fields. Federation lets each domain team own their piece of the schema independently.How it works:

Each team defines a subgraph — a standalone GraphQL service that owns specific types and fields.
Types that span multiple subgraphs are called entities, marked with @key(fields: "id"). Any subgraph can extend an entity by referencing its key.
A schema registry (Apollo Studio or Rover CLI) validates that all subgraphs compose without conflicts and produces the supergraph schema.
The gateway (Apollo Router) receives client queries, uses a query planner to determine which subgraphs to call and in what order, orchestrates the calls, and merges results into a unified response.

When to use it:

Multiple teams (3+) contributing to a single API
When schema bottleneck is slowing down product development
When you need domain-driven ownership of API surface area
When your organization has established service boundaries that map to subgraph ownership

When NOT to use it:

Small teams (1-2 engineers) — the operational overhead is not justified
Simple APIs that do not benefit from distributed ownership
When your services do not have clear domain boundaries

The key insight is that federation solves an organizational problem (who owns what in the schema) as much as a technical one. The technology is only worth it when you have enough teams that schema ownership is genuinely contested.

Design a GraphQL schema for an e-commerce platform with products, orders, and reviews.

What they are really testing: Schema design skills, understanding of GraphQL conventions (connections, pagination, input types), and ability to think about performance and authorization.Strong answer:I would design this iteratively, starting with core types and then layering in pagination, mutations, and authorization considerations.

# Core types
type Product {
  id: ID!
  name: String!
  description: String
  price: Money!
  category: Category!
  images: [Image!]!
  averageRating: Float          # Precomputed, avoids client-side aggregation
  reviewCount: Int!
  reviews(first: Int = 10, after: String): ReviewConnection!
  inStock: Boolean!
  variants: [ProductVariant!]!
}

type Order {
  id: ID!
  status: OrderStatus!
  items: [OrderItem!]!
  total: Money!
  createdAt: DateTime!
  shippingAddress: Address!
}

type Review {
  id: ID!
  rating: Int!                  # 1-5
  title: String
  body: String
  author: User!
  product: Product!
  createdAt: DateTime!
  helpfulCount: Int!
}

# Custom scalar for money (avoids floating point issues)
scalar Money
scalar DateTime

enum OrderStatus {
  PENDING
  CONFIRMED
  SHIPPED
  DELIVERED
  CANCELLED
  REFUNDED
}

# Relay-style pagination
type ReviewConnection {
  edges: [ReviewEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type ReviewEdge {
  cursor: String!
  node: Review!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

# Queries
type Query {
  product(id: ID!): Product
  products(
    first: Int = 20
    after: String
    category: ID
    search: String
    sortBy: ProductSortField = RELEVANCE
  ): ProductConnection!
  order(id: ID!): Order            # Auth: only the owner can see their order
  myOrders(first: Int = 10, after: String): OrderConnection!
}

# Mutations
type Mutation {
  createReview(input: CreateReviewInput!): CreateReviewPayload!
  placeOrder(input: PlaceOrderInput!): PlaceOrderPayload!
  cancelOrder(id: ID!): CancelOrderPayload!
}

input CreateReviewInput {
  productId: ID!
  rating: Int!
  title: String
  body: String
}

# Mutation payloads follow the convention of returning
# the created/modified object plus potential errors
type CreateReviewPayload {
  review: Review
  errors: [UserError!]!
}

type UserError {
  field: String
  message: String!
}

Key design decisions:

Money as a custom scalar — representing prices as floats is a classic bug. Use a scalar backed by integer cents or a decimal library.
Relay-style pagination on all lists — reviews, products, orders. Cursor-based for performance.
averageRating as a precomputed field — avoids the client needing to fetch all reviews to calculate an average. This is denormalization for performance.
Mutation payloads with errors — instead of throwing GraphQL errors for validation failures, return structured errors in the payload. This lets clients handle validation gracefully.
Authorization at the resolver level — order(id: ID!) must check that the authenticated user owns the order. This is not visible in the schema but is critical in the implementation.

In a federated setup, Products, Orders, and Reviews would each be separate subgraphs. The Product type would be an entity with @key(fields: "id"), and the Reviews subgraph would extend it with the reviews field.

How do you prevent malicious queries in a public GraphQL API?

What they are really testing: Security mindset and defense-in-depth thinking specific to GraphQL’s unique attack surface.Strong answer:GraphQL’s flexibility is its security challenge — clients can construct arbitrary queries. I would implement defense in depth with multiple layers:Layer 1: Query depth limiting. Set a maximum depth (typically 10-12). This prevents infinitely nested queries that exploit circular relationships. Cheap to implement, catches the most naive attacks.Layer 2: Query complexity analysis. Assign a cost to each field based on its computational expense. List fields cost more (multiplied by the first argument). Set a maximum complexity budget per request. Reject queries that exceed the budget before execution, returning a descriptive error with the calculated cost.Layer 3: Rate limiting by cost, not request count. A budget of 1000 cost units per minute. A simple { me { name } } costs 1 unit; a complex nested query costs 500. This prevents abuse without penalizing simple operations.Layer 4: Request timeout. Hard limit of 10-30 seconds per query execution. If a query takes longer, kill it. This is your safety net for anything that slips past complexity analysis.Layer 5: Persisted queries (if you control all clients). Only allow pre-registered query hashes. This is the most secure option because arbitrary queries are impossible.Layer 6: Disable introspection in production or gate it behind authentication. Without introspection, attackers cannot easily map your schema to craft targeted attacks.Layer 7: Input validation in resolvers. GraphQL validates types but not content. A String variable could contain SQL injection or XSS payloads. Parameterize database queries and sanitize outputs.Layer 8: Field-level authorization. Do not rely on root-level auth. Every resolver that returns sensitive data must verify the caller’s permissions. A query like { user(id: "other-user") { email ssn } } must be authorized at the field level, not just at the query level.The key insight is that GraphQL shifts the attack surface from “which endpoints are exposed” (REST) to “what queries can be constructed” (GraphQL). Your security model must account for the combinatorial nature of GraphQL queries.

What is the N+1 problem in GraphQL and how do you solve it?

What they are really testing: Whether you understand the fundamental performance characteristic of GraphQL’s resolver model and the standard solution.Strong answer:The N+1 problem occurs because GraphQL resolves each field independently. When you query a list of N items and each item has a related field, the parent query runs once (1 query), then the related field’s resolver runs N times — one per item — producing N+1 total database queries.Example: Querying 50 products with their reviews. The products resolver runs one query returning 50 products. Then the reviews resolver on each product fires individually: 50 separate SELECT * FROM reviews WHERE product_id = ? queries. Total: 51 queries.The solution is the DataLoader pattern. Instead of each resolver immediately hitting the database, it registers a “load request” with a DataLoader instance. The DataLoader waits until the current execution tick completes, collects all pending requests, and makes one batched query: SELECT * FROM reviews WHERE product_id IN (1, 2, 3, ..., 50). One query instead of 50.Critical implementation details:

DataLoaders must be per-request (created in the request context) — sharing across requests leaks data between users
The batch function must return results in the same order as the input keys
DataLoaders also deduplicate — if two fields request the same entity by ID, only one database call is made
Layer an external cache (Redis) under DataLoader for cross-request caching

Monitoring: Count database queries per GraphQL operation in production. If any operation consistently exceeds O(query depth) queries, you likely have an N+1 issue in a resolver that is missing a DataLoader.

Compare Apollo Client, Relay, and urql. When would you choose each?

What they are really testing: Client-side GraphQL experience and the ability to reason about trade-offs in library selection.Strong answer:Apollo Client is the most popular and feature-rich. Its normalized cache stores entities by ID, so updating a product in one query automatically updates it everywhere it appears. It has excellent dev tools (Apollo DevTools browser extension), supports every GraphQL feature (subscriptions, defer, optimistic updates), and has the largest community. The trade-off: it is the largest bundle (~30-40KB gzipped), and the normalized cache can be complex to manage (cache eviction, manual cache updates after mutations). Choose Apollo Client for: Most production applications, especially if your team wants comprehensive tooling and does not mind the bundle size.Relay is Facebook’s client, designed for extreme scale. It uses a compiler that runs at build time to optimize queries, generate types, and produce persisted query artifacts. Its fragment colocation model forces you to define data requirements at the component level, which eliminates over-fetching by design. The trade-off: the learning curve is the steepest of any GraphQL client. It requires strict conventions (Relay-compliant schema with Node interface, connection-based pagination). Choose Relay for: Large teams (50+ engineers) building data-intensive applications where the compiler-driven approach pays for its learning cost.urql is lightweight (~7KB gzipped) and built on an exchangeable architecture — you add features via “exchanges” (plugins). Its document cache is simpler than Apollo’s normalized cache (it caches by query, not by entity). The trade-off: less sophisticated caching means more manual cache management for complex apps. Choose urql for: Smaller applications, teams that want less abstraction, or projects where bundle size matters.My recommendation: Default to Apollo Client unless you have a specific reason not to. Move to Relay only if you are at a scale where its compiler-driven approach provides measurable benefits. Use urql for smaller projects or if you strongly prefer its minimalist philosophy.

How would you migrate a REST API to GraphQL without a big-bang rewrite?

What they are really testing: Pragmatic migration thinking, understanding of the strangler fig pattern, and realistic assessment of risks.Strong answer:I would use a GraphQL gateway as a facade over existing REST services — the strangler fig pattern applied to API evolution.Phase 1: Gateway layer. Build a GraphQL server whose resolvers delegate to your existing REST endpoints. The frontend starts consuming GraphQL; the backend does not change at all. This is low risk because you are not rewriting business logic — the GraphQL layer is purely a translation layer.

const resolvers = {
  Query: {
    product: async (_, { id }) => {
      // Delegates to existing REST endpoint
      const res = await fetch(`http://product-service/api/v1/products/${id}`);
      return res.json();
    },
  },
};

Phase 2: Incremental adoption. Migrate one domain at a time. Start with the domain where GraphQL adds the most value (typically the one with the most over-fetching or the most client variation). As each domain migrates, its resolvers move from calling REST endpoints to calling the database or service directly.Phase 3: Schema optimization. Once the GraphQL layer is stable, optimize the schema for GraphQL’s strengths — add connections for pagination, introduce fragments for reusable data shapes, implement DataLoaders for batching.Phase 4: Deprecate REST endpoints. As frontend clients fully migrate to GraphQL, deprecate the REST endpoints they used. Keep REST for server-to-server communication or public APIs where REST is expected.Key risks to manage:

Performance regression: The GraphQL gateway adds a network hop. Monitor latency carefully in Phase 1.
Consistency: During migration, some data comes through GraphQL, some through REST. Ensure clients do not mix paradigms for the same data.
Team buy-in: If the backend team does not see value in GraphQL, the migration stalls. Demonstrate concrete wins (fewer endpoints to maintain, less over-fetching) early.

You are building a real-time feature using GraphQL subscriptions. Walk through the architecture.

What they are really testing: Understanding of WebSocket infrastructure, pub/sub patterns, and the operational complexity of persistent connections.Strong answer:Let’s say we are building real-time order status updates for an e-commerce platform.Client side:

subscription OnOrderStatusChanged($orderId: ID!) {
  orderStatusChanged(orderId: $orderId) {
    id
    status
    updatedAt
    estimatedDelivery
  }
}

The client establishes a WebSocket connection using the graphql-ws protocol. When the user opens an order details page, the client subscribes. When they leave, the subscription is torn down.Server architecture:

WebSocket server — handles connection lifecycle (connect, subscribe, unsubscribe, disconnect). Each connection is authenticated on connect. Use graphql-ws library (the successor to the deprecated subscriptions-transport-ws).
Pub/Sub backend — when a mutation updates an order’s status, it publishes an event to Redis Pub/Sub (or Kafka for durability):

// In the updateOrderStatus mutation resolver
await db.orders.update(orderId, { status: newStatus });
await pubsub.publish(`ORDER_STATUS_${orderId}`, {
  orderStatusChanged: { id: orderId, status: newStatus, updatedAt: new Date() }
});

Subscription resolver — filters events for the specific order:

const resolvers = {
  Subscription: {
    orderStatusChanged: {
      subscribe: (_, { orderId }) =>
        pubsub.asyncIterator(`ORDER_STATUS_${orderId}`),
    },
  },
};

Scaling considerations:
- WebSocket connections are stateful and pinned to a server instance. You need sticky sessions at the load balancer level.
- Redis Pub/Sub broadcasts events to all server instances. Each instance checks if it has subscribers for that event and pushes updates accordingly.
- Monitor: active connection count per instance, subscription count per topic, message delivery latency, disconnection rate.
Fallback strategy: For clients that cannot maintain WebSocket connections (corporate firewalls, intermittent mobile connections), implement a polling fallback. The subscription resolver can gracefully degrade: if WebSocket fails, the client polls every 5 seconds via a regular query.

The honest trade-off: Subscriptions add significant operational complexity. For many use cases (order tracking where updates happen every few minutes), polling every 10 seconds provides a comparable user experience with dramatically simpler infrastructure. I would start with polling and only move to subscriptions if the latency requirement genuinely demands it.

How do you handle schema evolution in a GraphQL API without breaking clients?

What they are really testing: Understanding of backward compatibility, deprecation workflows, and the practical challenges of evolving a schema used by multiple clients.Strong answer:The golden rule: GraphQL schemas should evolve additively. You add fields, you never remove them abruptly.Safe changes (deploy anytime):

Adding a new field to an existing type
Adding a new type
Adding a new argument with a default value
Adding a new query or mutation

Dangerous changes (require coordination):

Adding a new enum value (clients with exhaustive switch statements may break)
Making a nullable field non-nullable (existing queries that handle null will not expect non-null)

Breaking changes (must go through deprecation):

Removing a field
Renaming a field (this is effectively a remove + add)
Changing a field’s return type

The deprecation workflow:

Mark as deprecated: Add @deprecated(reason: "Use priceV2 instead. This field will be removed on 2026-06-01.") with a specific date.
Monitor usage: Use field-level analytics (Apollo Studio, custom Prometheus metrics) to track how many operations still reference the deprecated field.
Notify consumers: If you have a public API, announce the deprecation in your changelog. For internal APIs, notify consuming teams directly.
Grace period: Give consumers at least 3-6 months for public APIs, 1-2 sprints for internal APIs.
Remove: Once usage is at zero (or near-zero with a specific migration plan for remaining consumers), remove the field.

Tooling for CI:

graphql-inspector or Apollo’s rover CLI can compare the current schema against the previous version and flag breaking changes in pull requests
Commit your schema as a snapshot (.graphql file) and diff it in CI
Block merging PRs that introduce unintentional breaking changes

The key insight: schema evolution is a communication problem as much as a technical one. The best tools catch mistakes, but the real discipline is having a deprecation policy and following it consistently.

Explain the trade-offs between cursor-based and offset-based pagination in GraphQL.

What they are really testing: Understanding of pagination at a systems level and why the industry has converged on cursors for GraphQL.Strong answer:Offset-based: products(offset: 20, limit: 10) — skip the first 20, return the next 10.Pros: Simple to implement. Easy to jump to “page 5.” Maps directly to SQL LIMIT/OFFSET.Cons:

Consistency problem: If an item is inserted or deleted while the user is paginating, they may see duplicates or miss items. Page 2 might overlap with page 1 if a new item was inserted.
Performance problem: OFFSET 10000 in SQL forces the database to scan and discard 10,000 rows before returning the next page. This gets progressively slower for deep pages.
Not suitable for infinite scroll: Users who scroll through thousands of items will experience degrading performance.

Cursor-based (Relay Connection spec): products(first: 10, after: "cursor_abc") — return 10 items after this cursor.Pros:

Consistent: Cursors point to a specific position in the dataset. Inserts and deletes do not cause duplicates or gaps.
Fast at any depth: The database query uses WHERE id > cursor_value ORDER BY id LIMIT 10, which is index-friendly and constant-time regardless of how deep you are in the list.
Standardized: The Relay Connection spec is well-understood, supported by tooling, and expected by experienced GraphQL developers.

Cons:

Cannot jump to arbitrary pages: There is no “go to page 5” — you can only move forward or backward from a cursor. For UIs that need page numbers, this is a limitation.
More complex implementation: The connection/edge/pageInfo structure is more verbose than a simple array.
Cursor encoding: Cursors should be opaque (base64-encoded) so clients do not try to construct them. This adds a layer of encoding/decoding.

My recommendation: Default to cursor-based pagination for GraphQL APIs. The consistency and performance guarantees are worth the added complexity. If you need “jump to page N” functionality (admin dashboards, data tables), consider a hybrid: cursor-based for the primary API, with an optional offset argument for administrative use cases only.

How do you handle errors in a GraphQL API? Walk through your error handling strategy.

What they are really testing: Whether you understand GraphQL’s unique error model (HTTP 200 with errors in the body), the distinction between system errors and business logic errors, and how to build a client-side error handling layer.Strong answer:GraphQL’s error model is fundamentally different from REST. The server almost always returns HTTP 200, with errors communicated in a structured errors array. This means traditional HTTP monitoring sees 100% success rates even when the API is failing constantly — you must inspect the response body.I structure errors into three categories:1. Execution errors — unexpected system failures (database timeouts, downstream service unavailability). These throw in the resolver, return null for the affected field, and appear in the top-level errors array with an extensions.code like INTERNAL_SERVER_ERROR or DOWNSTREAM_SERVICE_ERROR. The client gets partial data for everything that did resolve successfully.2. Validation/business logic errors — expected failures like “email already taken” or “insufficient inventory.” These should NOT go in the top-level errors array. Instead, I return them in the mutation payload using a UserError type with field, message, and code. This follows the Shopify/GitHub convention and gives clients structured, predictable error information they can map to UI form fields.

type CreateOrderPayload {
  order: Order
  errors: [UserError!]!
}

3. Authorization errors — I use extensions.code: "UNAUTHENTICATED" for missing auth and "FORBIDDEN" for insufficient permissions. These go in the top-level errors because they represent a fundamental access problem, not a business logic outcome.On the client side, I build an error classification layer that inspects extensions.code and routes to the appropriate handler: auth errors redirect to login, rate limit errors trigger retry-after logic, system errors show a generic “something went wrong” message, and business logic errors from the payload are displayed inline on the relevant form fields.For monitoring, I parse the errors array in our observability pipeline (Datadog custom metrics) and alert on error rate by operation name and error code. A spike in DOWNSTREAM_SERVICE_ERROR for the GetProductPage operation tells me exactly what is wrong and where.The key insight is that GraphQL’s partial response capability is a feature, not a bug. Design your UI to render what you have and gracefully degrade what you do not, rather than treating any error as a total page failure.

Your team is considering migrating from REST to GraphQL. How would you plan and execute this migration?

What they are really testing: Pragmatic migration planning, risk management, organizational awareness, and the ability to articulate a phased strategy rather than a big-bang rewrite.Strong answer:I would approach this as a phased migration with clear validation gates between phases.Phase 0: Validation. First, confirm GraphQL actually solves a real problem for us. The three signals I look for: (1) multiple clients requesting different shapes of the same data (over-fetching), (2) the frontend team is bottlenecked on backend API changes, (3) our data model is graph-shaped with deep relationships. If at least two of these are true, GraphQL is worth the investment.Phase 1: GraphQL gateway over existing REST (weeks 1-4). Build a thin GraphQL server whose resolvers delegate to existing REST endpoints. No business logic moves. The schema is designed for how the frontend wants to consume data, not how REST happens to structure it. Authentication is passed through — the GraphQL layer forwards tokens to downstream REST services. This is the lowest-risk starting point because the REST API remains the source of truth.Phase 2: Client migration, screen by screen (weeks 4-12). Start with the highest-value screen — the one making the most REST calls or suffering the most from over-fetching. Use feature flags to toggle between REST and GraphQL data sources per screen. Measure: API calls per page load, bytes transferred, time to first meaningful paint. These metrics justify the migration to stakeholders.Phase 3: Resolver optimization (weeks 8-16). Add DataLoaders for N+1 prevention. Migrate high-traffic resolvers from REST delegation to direct database access, eliminating the extra network hop. Add @cacheControl directives and Redis caching. This is where the performance benefits materialize.Phase 4: REST deprecation (ongoing). Monitor REST endpoint usage. Deprecate endpoints fully replaced by GraphQL. Keep REST for server-to-server communication, public APIs, file uploads, and webhooks.Key risks I would manage:

Latency regression in Phase 1 (the gateway adds a hop). Monitor P99 latency from day one.
Team buy-in — demonstrate concrete wins (fewer endpoints, less over-fetching) early to maintain momentum.
Coexistence complexity — during migration, both APIs must share the same auth mechanism and the same source of truth for each data domain.

The most important thing I would communicate to stakeholders: this is not a rewrite, it is a layering strategy. The GraphQL API starts as a facade, and we migrate the internals incrementally based on measured value.

What GraphQL tooling would you set up for a production API, and why?

What they are really testing: Awareness of the GraphQL ecosystem beyond the runtime, operational maturity, and the ability to build a sustainable development workflow.Strong answer:I would set up tooling in four categories: development, CI/CD safety, runtime observability, and client-side type safety.Development:

GraphiQL or Apollo Explorer for interactive query development and debugging. Gated behind authentication in production, fully open in staging.
graphql-eslint for linting GraphQL operations in the codebase — enforce operation naming conventions, prevent usage of deprecated fields, require variables instead of inline arguments.

CI/CD safety:

GraphQL Inspector (or Apollo’s rover subgraph check) running on every PR that modifies the schema. It compares the proposed schema against the current production schema and flags breaking changes, dangerous changes, and safe changes. This is the single most important tool for preventing production incidents from schema evolution.
Schema snapshot tests — commit the schema as a .graphql file and fail CI when it changes without explicit acknowledgment. This catches unintentional schema changes from code-first approaches.
Composition validation for federation — every subgraph change must compose successfully with the supergraph before merging.

Runtime observability:

Apollo Studio (or GraphQL Hive for self-hosted) for operation-level and field-level analytics. Per-operation latency, error rates, and field usage data. The field usage data is critical for deprecation — you cannot safely remove a field unless you know who is using it. Without this data, schema evolution is guesswork.
Custom Prometheus metrics exported from the GraphQL middleware: operation name, latency histogram, error count by code, resolver duration. Visualized in Grafana dashboards showing operations per minute, P50/P99 latency, and the slowest resolvers.
GraphQL-aware error parsing in the APM layer — because HTTP status is always 200, the monitoring pipeline must inspect the errors array to detect real failures.

Client-side type safety:

graphql-codegen generating TypeScript types and React hooks from the schema and client operations. This eliminates the entire class of “field was renamed and nobody told the frontend” bugs. I run codegen as a pre-commit hook and in CI so types are always in sync with the schema.

The minimum viable stack for a small team: graphql-codegen + GraphQL Inspector in CI + DataLoader + depth/complexity limiting. You can ship production GraphQL with zero vendor costs using entirely open-source tooling. Apollo Studio and GraphOS add significant value for federated architectures but are not required for smaller setups.

Real-World Case Studies

GitHub: The GraphQL Pioneer

GitHub’s GraphQL API (v4) is one of the most used public GraphQL APIs in the world. Key decisions and lessons:

Schema governance: GitHub uses a schema review process where every new field and type is reviewed for naming consistency, deprecation plans, and performance implications. Their schema is remarkably consistent across hundreds of types.
Query complexity: GitHub assigns a “node limit” to each query. You can request a maximum of 500,000 nodes per query (a node is any object in the response). They return remaining rate limit data in every response via the rateLimit field.
Pagination: Strict Relay Connection spec everywhere. Every list field uses connections with edges and pageInfo.
Introspection: Enabled in production (it is a public API), but combined with aggressive rate limiting and complexity analysis.

Lesson: GitHub proved that GraphQL can work for public APIs at massive scale, but only with serious investment in schema governance, rate limiting, and monitoring.

Shopify: Cost-Based Rate Limiting at Scale

Shopify’s Storefront and Admin APIs serve millions of merchants. Their contribution to the GraphQL ecosystem:

Calculated query cost: Every query has a cost calculated before execution. The cost is based on which fields are requested and how many items are in each list. They expose the cost in the response so developers can optimize.
Leaky bucket rate limiter: Instead of fixed windows, Shopify uses a leaky bucket: you have a “bucket” of cost credits that refills at a constant rate. Bursts are allowed up to the bucket size, but sustained abuse drains the bucket.
Schema design for e-commerce: Shopify’s schema is a masterclass in e-commerce domain modeling — products with variants, metafields for custom data, fulfillments, inventory levels. Studying their schema is valuable for anyone designing e-commerce APIs.

Lesson: Shopify demonstrated that cost-based rate limiting is essential for production GraphQL. Simple request counting is insufficient when one query can be 1000x more expensive than another.

Airbnb: GraphQL as an Integration Layer

Airbnb adopted GraphQL as a frontend gateway on top of their existing service-oriented architecture:

Gateway pattern: GraphQL resolvers delegate to internal REST and Thrift services. The GraphQL layer does not own data — it orchestrates.
Schema ownership: Domain teams own their portion of the schema. The platform team owns the gateway infrastructure and schema composition.
Type safety pipeline: GraphQL schema generates TypeScript types, which are consumed by the React frontend. End-to-end type safety from database to UI.
Performance: Airbnb invested heavily in DataLoader patterns and response caching to ensure the gateway layer did not add unacceptable latency.

Lesson: GraphQL does not have to replace your backend. It can sit in front of it as a purpose-built frontend integration layer, providing flexibility to the UI without rewriting services.

Curated Resources

Essential reading and tools for GraphQL at scale:Foundational:

GraphQL official specification — the actual spec, surprisingly readable. Understand the execution model at the source.
graphql.org/learn — the official introduction. Best starting point for fundamentals.
How to GraphQL — free full-stack tutorial covering both client and server.

Federation and Architecture:

Apollo Federation documentation — the definitive guide to federated GraphQL. Covers v2 entities, composition, and gateway.
Apollo Router documentation — the Rust-based federation gateway. Significantly faster than the Node.js Apollo Gateway.
The Guild’s GraphQL Tools — open-source schema stitching, code generation, and utilities. A strong alternative to Apollo’s ecosystem.

Client Libraries:

Apollo Client documentation — normalized caching, optimistic UI, and dev tools.
Relay documentation — Facebook’s compiler-driven client. The “Thinking in Relay” guide is essential reading for understanding fragment colocation.
urql documentation — lightweight and extensible.

Performance and Security:

Shopify’s API rate limiting documentation — the gold standard for cost-based GraphQL rate limiting.
GitHub GraphQL API rate limiting — node-based limiting approach.
graphql-codegen — generates TypeScript types, React hooks, and SDK code from your schema. Eliminates an entire class of bugs.

Advanced:

Marc-Andre Giroux’s “Production Ready GraphQL” — the best book on GraphQL schema design, performance, and organizational patterns at scale.
Apollo Blog: Principled GraphQL — best practices for treating your graph as a first-class product.
Netflix Tech Blog: GraphQL Federation at Netflix — real-world federation at massive scale.

Connection to other chapters: This chapter sits at the intersection of many production engineering concerns. Each connection below tells you where to go for deeper treatment of a concept introduced here:

APIs and Databases — The GraphQL vs REST comparison here covers query flexibility and caching trade-offs. That chapter goes deeper into REST API design (Stripe’s versioning, idempotency keys, pagination), gRPC for server-to-server communication, and database indexing strategies that directly affect resolver performance. When this chapter says “add an index to fix a slow resolver,” that chapter explains B-tree internals and query planner behavior.
Database Deep Dives — The N+1 problem and DataLoader patterns here are the GraphQL-specific view of a deeper database performance story. That chapter covers PostgreSQL MVCC, query planning with EXPLAIN, connection pooling, and DynamoDB partition strategies — all of which matter when your GraphQL resolvers hit the database layer.
Caching and Observability — GraphQL’s biggest disadvantage versus REST is caching. This chapter covers persisted queries and @cacheControl directives. That chapter covers the foundational caching patterns (write-through, write-behind, cache-aside), invalidation strategies (TTL, event-driven, lease-based), and CDN caching layers that you need to make GraphQL caching work at scale. Facebook’s Memcached architecture described there is directly relevant to cross-request caching in federated GraphQL.
Auth and Security — Query complexity analysis and introspection controls are GraphQL-specific security concerns. That chapter covers the underlying authentication patterns (OAuth 2.0, OIDC, JWT validation), authorization models (RBAC, ABAC), and the OWASP Top 10 — all of which apply to GraphQL. Field-level authorization in resolvers is the GraphQL implementation of the principle of least privilege discussed there.
Real-Time Systems — GraphQL subscriptions use WebSocket under the hood. That chapter is the deep dive: WebSocket protocol internals, connection lifecycle, scaling persistent connections with sticky sessions, Server-Sent Events as an alternative, and conflict resolution (CRDTs, operational transforms). If you are building GraphQL subscriptions at scale, read that chapter’s WebSocket scaling section first.
API Gateways and Service Mesh — Apollo Router is a GraphQL-specific gateway, but it operates in the same architectural layer as Kong, Envoy, and Istio. That chapter covers gateway patterns (rate limiting, TLS termination, authentication, request routing) and service mesh concepts (sidecar proxies, mTLS) that apply when your federated GraphQL subgraphs run in a microservice architecture. The “GraphQL at the gateway” pattern — where the API gateway routes GraphQL traffic, enforces rate limits, and handles auth before the request reaches your GraphQL server — is a direct application of the gateway patterns described there.
Performance and Scalability — Query optimization, connection pooling, async processing, and backpressure patterns from that chapter apply directly to GraphQL resolver performance. The thundering herd problem described there (Twitter’s Fail Whale) is exactly what happens when a popular GraphQL query is not cached and hits your database on every request.
Testing, Logging, and Versioning — Schema snapshot testing, contract tests for federation, and the deprecation workflow described in this chapter are GraphQL-specific applications of the broader testing strategy and versioning discipline covered there. The Knight Capital case study in that chapter is a cautionary tale about what happens when deployment verification (analogous to schema composition checks in federation) is skipped.
Messaging, Concurrency, and State — Subscription architecture relies on pub/sub patterns (Redis Pub/Sub, Kafka) covered extensively there. The event-driven architecture behind “mutation triggers event, event triggers subscription push” is the same pattern used in event sourcing and CQRS systems.
Multi-Tenancy, DDD, and Documentation — Federation is a practical application of domain-driven design. Subgraph ownership maps to bounded contexts. Schema governance maps to context mapping. That chapter provides the organizational and architectural theory behind why federation works when subgraphs follow domain boundaries and fails when they do not.

Interview Deep-Dive Questions

These questions go beyond surface-level knowledge. They simulate the multi-round probing that happens in senior and staff-level interviews — where the interviewer keeps digging until they find the boundary of your understanding.

1. You inherit a federated GraphQL API where the gateway’s P99 latency has degraded from 200ms to 1.2 seconds over the past quarter. Walk me through how you diagnose and fix this.

What the interviewer is really testing: Can you reason about performance in a distributed system with multiple moving parts (gateway, subgraphs, databases, network)? Do you have a systematic debugging methodology, or do you start guessing? Strong answer: I would work outside-in, from the broadest signal to the narrowest cause. Step 1: Identify which operations degraded. Not all operations are slow — P99 is a tail metric. I would pull operation-level latency data from Apollo Studio or our Prometheus metrics and sort by P99 increase over the quarter. Often it is 3-5 operations responsible for the entire regression. If every operation degraded uniformly, that points to infrastructure (gateway CPU, network, TLS overhead), not application logic. Step 2: Examine the gateway query plans for the slowest operations. Apollo Router (or Apollo Gateway) generates a query plan for each incoming operation — which subgraphs to call, in what order, and what data to pass between them. I would trace the slowest operations and look for waterfall patterns: sequential subgraph calls where the gateway fetches from subgraph A, waits, then fetches from subgraph B using data from A, waits again, then fetches from subgraph C. A new @requires directive added in the past quarter could introduce a previously-parallel call into a sequential chain, adding 200-400ms per hop. Step 3: Check if new subgraphs or fields were added. Schema changes over a quarter are the most likely culprit for gradual degradation. A new team might have added a subgraph with slow resolvers, or an existing subgraph might have added fields that trigger expensive database queries. I would diff the supergraph schema between the start and end of the quarter and correlate with the latency timeline. Step 4: Subgraph-level latency. For the offending operations, check the per-subgraph response time. If the gateway is calling subgraph X and it takes 800ms, the problem is in subgraph X, not the gateway. Drill into that subgraph’s resolver traces — look for missing DataLoaders, N+1 queries, or slow downstream service calls. Step 5: Gateway infrastructure. If subgraphs are all fast but the gateway is slow, check: (a) CPU utilization on the gateway instances — query planning is CPU-bound, and if traffic grew while instance count stayed flat, you get CPU contention; (b) memory pressure if caching supergraph schemas in-memory; (c) whether the gateway was upgraded or the supergraph schema grew significantly (more types = more complex query planning). Step 6: Fix based on root cause. If it is waterfall dependencies, restructure the schema to reduce cross-subgraph @requires chains. If it is a slow subgraph, add DataLoaders or caching. If it is gateway infrastructure, scale horizontally or migrate from the Node.js Apollo Gateway to the Rust-based Apollo Router, which handles query planning significantly faster.

Follow-up: How would you prevent this kind of gradual degradation from happening again?

I would establish performance budgets per operation and alert on regressions in CI and production. In CI: add a schema check step that simulates query plans for critical operations after every subgraph schema change. If a change introduces a new sequential subgraph dependency that increases the estimated latency of a critical operation by more than some threshold, the build fails with a warning. Apollo’s rover subgraph check can validate composition, but for performance budgets you would need a custom step that runs the query planner against representative operations and asserts on the plan shape (number of sequential fetches, number of subgraphs involved). In production: set up Prometheus alerts on P95 and P99 latency per named operation. If GetProductPage P99 exceeds 500ms for more than 15 minutes, page the on-call team. The key is per-operation alerting, not aggregate — aggregate latency hides regressions in specific operations. Organizationally: require a “performance impact” section in every subgraph schema change PR. If you are adding a @requires directive or a new entity reference, document the expected cross-subgraph call pattern. This is the same discipline as writing migration notes for database changes — it forces the author to think about the operational impact.

Follow-up: What is the difference between Apollo Gateway and Apollo Router, and when does the choice matter?

Apollo Gateway is the original Node.js-based federation gateway. Apollo Router is the newer Rust-based replacement. The functional behavior is identical — both read the supergraph schema, plan queries, and orchestrate subgraph calls. The difference is raw performance. Query planning is CPU-bound: the gateway parses the incoming operation, walks the supergraph schema to determine which subgraphs own which fields, builds a dependency graph of subgraph calls, and serializes the execution plan. In Node.js, this is single-threaded and GC-paused. In Rust, it is multi-threaded with no GC pauses. At low traffic, the difference is negligible. At high traffic (thousands of requests per second) or with complex supergraphs (20+ subgraphs, deeply nested operations), the Router can be 5-10x faster at query planning. The choice matters when you are seeing elevated P99 latencies that correlate with gateway CPU utilization rather than subgraph response time. If your traces show that subgraphs respond in 50ms but the total gateway response time is 400ms, the extra 350ms is query planning overhead. That is when migrating from Gateway to Router gives immediate, measurable improvement. For a small team with 2-3 subgraphs and moderate traffic, either works fine. For a large organization at scale, Router is the clear choice.

Going Deeper: How does the federation query planner actually decide the order of subgraph calls?

The query planner builds a dependency graph by walking the incoming operation against the supergraph schema. For each field in the query, it knows which subgraph owns that field. When a field in subgraph B depends on data from subgraph A (via @requires or entity resolution), it creates an edge from A to B in the dependency graph. The planner then topologically sorts this graph. Independent subgraph calls (no dependencies between them) are executed in parallel. Dependent calls are executed sequentially — the gateway waits for the upstream subgraph to return before calling the downstream one. For example: if the client queries { product(id: "42") { name price reviews { rating } shippingCost } }, and name/price are in the Products subgraph, reviews are in the Reviews subgraph, and shippingCost is in the Shipping subgraph with @requires(fields: "weight") where weight comes from Products — the planner will:

Call Products subgraph (gets name, price, weight)
In parallel: call Reviews subgraph (gets reviews) AND call Shipping subgraph (gets shippingCost, using weight from step 1)

The planner is smart enough to batch the entity resolution call to Reviews and the @requires-driven call to Shipping into a single parallel step since neither depends on the other. The worst case is a chain of @requires directives where each subgraph depends on data from the previous one — that creates a fully sequential waterfall.

2. You are designing the authorization model for a federated GraphQL API. Where does auth logic live, and how do you prevent a subgraph from leaking data it should not?

What the interviewer is really testing: Do you understand the unique auth challenges of GraphQL (field-level granularity, federation boundary crossing, the “one endpoint” problem), or do you just say “check the token in middleware” and stop there? Strong answer: Authorization in GraphQL is fundamentally more granular than REST because the client controls which fields are requested. In REST, you authorize per endpoint. In GraphQL, you must authorize per field — or at minimum, per type. Here is how I structure it. Layer 1: Authentication at the gateway. The gateway validates the JWT or session token on every request. If the token is invalid, the request is rejected with an UNAUTHENTICATED error before any subgraph is called. The gateway extracts the user identity and permissions from the token and passes them to subgraphs via request headers (typically a custom header like x-user-id and x-user-roles). Layer 2: Authorization in each subgraph resolver. This is where people make mistakes. It is tempting to put all auth logic in the gateway, but that violates the principle of federation — each subgraph owns its domain, including who can access what. The Orders subgraph knows that only the order owner (or an admin) should see order details. The gateway should not need to know this business rule. In practice, I implement auth as a resolver middleware or directive:

type Order @key(fields: "id") {
  id: ID!
  status: OrderStatus!
  items: [OrderItem!]! @auth(requires: OWNER)
  total: Money! @auth(requires: OWNER)
  internalNotes: String @auth(requires: ADMIN)
}

The @auth directive is implemented as a resolver wrapper that checks the user context (passed from the gateway) against the authorization rule before the resolver executes. If the check fails, the field returns null with a FORBIDDEN error in the errors array. Layer 3: Entity resolution security. This is the federated gotcha. When the Reviews subgraph receives an _entities call to resolve Product entities, it must trust that the gateway has already authenticated the request. But it must not trust that the caller is authorized to see every field. If the Reviews subgraph extends Product with a moderationFlags field that only admins should see, that auth check must happen in the Reviews subgraph’s resolver, not rely on the gateway. Layer 4: Field-level visibility. Some fields should not even appear in the schema for certain users. This is harder — GraphQL introspection shows the full schema to everyone. Options: (a) disable introspection in production; (b) use schema masking (Apollo Router supports this) to serve different schema views based on the caller’s role; (c) accept that the schema is visible but enforce authorization at the resolver level so unauthorized access returns null.

Follow-up: A developer on the Reviews team adds a resolver that returns user email addresses without any auth check. How do you catch this before production?

This is a governance and process problem as much as a technical one. I would layer multiple safeguards: Automated: Add a custom schema linting rule (via graphql-eslint or a custom CI check) that flags any field returning a type known to contain PII (like User or Email) that lacks an @auth directive. This is a heuristic — it catches the obvious cases. Code review: Subgraph schema changes go through a review process that includes a security-focused reviewer. The review checklist includes: “Does every new field that returns user data have appropriate authorization?” This is the same discipline as reviewing database migration scripts for sensitive column access. Integration testing: Write authorization test cases for every entity type: “As an unauthenticated user, querying [entity] should return UNAUTHENTICATED.” “As user A, querying user B’s [entity] should return FORBIDDEN or null.” These tests run against the composed supergraph in CI. Runtime monitoring: Even with all the above, mistakes happen. Monitor for unusual field access patterns — if the reviews.author.email field suddenly starts getting requested at 10x its normal rate, that could indicate that a client discovered an unprotected field. Alert on anomalous field usage spikes. The key insight is that authorization in federated GraphQL requires defense in depth because the system has multiple entry points (each subgraph) and the schema is discoverable.

Follow-up: How does this compare to authorization in a REST API?

In REST, authorization is typically per-endpoint. You put an auth middleware on /api/orders/:id that checks if the caller owns the order. Every request to that endpoint returns the same fields, so field-level authorization is rarely needed. In GraphQL, the same “endpoint” (/graphql) can return vastly different data depending on the query. A query for { order(id: "1") { status } } might be fine for any authenticated user to see, but { order(id: "1") { items { sku price } paymentMethod { last4 } } } reveals financial information that only the owner should access. Same endpoint, same type, different fields, different authorization requirements. This means GraphQL authorization is inherently more complex. The attack surface is larger because the client controls what data to request. You cannot rely on “this endpoint is protected” — you need “this field is protected.” The tradeoff is that GraphQL gives you a single place (the schema) where you can declaratively express authorization rules (@auth directives), which can actually be more auditable than scattered REST middleware if done well.

3. Your DataLoader is not batching as expected — individual resolvers are still firing separate database queries. What went wrong?

What the interviewer is really testing: Deep understanding of DataLoader’s batching mechanism (event loop ticks), common implementation mistakes, and the ability to debug a non-obvious performance issue. Strong answer: DataLoader batches requests that are enqueued during the same tick of the event loop (in Node.js) or the same execution phase. If individual queries are still firing, something is breaking the batching window. Here are the most common causes, in order of how often I have seen them: 1. Awaiting inside a loop instead of using Promise.all. This is the number one cause. If a resolver does this:

// BROKEN: each iteration awaits, so each load() runs in a separate tick
for (const product of products) {
  const reviews = await reviewLoader.load(product.id);
  // ...
}

Each await yields control back to the event loop, so the DataLoader dispatches the batch after each iteration. The fix is to collect all promises and resolve them together:

// CORRECT: all load() calls happen in the same tick
const reviewPromises = products.map(p => reviewLoader.load(p.id));
const allReviews = await Promise.all(reviewPromises);

2. DataLoader created at the wrong scope. If the DataLoader is created inside the resolver function instead of in the request context, each resolver invocation gets a fresh DataLoader with an empty batch queue. The whole point of DataLoader is that multiple resolvers share the same instance so their requests can be batched together. 3. The batch function has a bug in result ordering. DataLoader requires the batch function to return results in the exact same order as the input keys. If your batch function returns results in database order (which may differ from the input key order), DataLoader cannot correctly map results to requestors. It will not throw an error — it will silently return wrong data. This does not prevent batching per se, but it is the most common bug in DataLoader implementations and can look like batching is broken when debugging. 4. Using an async framework that does not have the same event loop semantics. DataLoader was designed for Node.js’s event loop. If you are using it in a different runtime (Deno, Bun, or a non-Node GraphQL server), the batching tick may behave differently. In some cases, you need to provide a custom batchScheduleFn to control when the batch dispatches. 5. GraphQL execution engine executing resolvers sequentially. Some GraphQL server implementations resolve sibling fields sequentially rather than concurrently. If your server resolves field A, dispatches its DataLoader batch, then resolves field B, the two fields’ loads will never be in the same batch. This is rare with major frameworks (Apollo Server, graphql-js resolve sibling fields concurrently) but can happen with less common implementations.

Follow-up: How would you test that DataLoader is actually batching correctly?

I would add instrumentation at the batch function level. Wrap the batch function with logging that records the batch size on every invocation:

const reviewLoader = new DataLoader(async (keys) => {
  console.log(`[DataLoader] Batching ${keys.length} review lookups`);
  // ... actual batch query
});

In integration tests, I would send a GraphQL query requesting 50 products with reviews and assert that the batch function is called exactly once (or a small number of times if there are multiple ticks) with approximately 50 keys, rather than being called 50 times with 1 key each. For production monitoring, I track a custom metric: dataloader_batch_size histogram. If the P50 batch size for a loader is 1, batching is not working. If it matches the expected cardinality of the parent list, it is working correctly. This metric is cheap to collect and immediately diagnostic.

Follow-up: Can DataLoader cause data consistency issues within a single request?

Yes, because DataLoader caches results for the lifetime of the instance (which is the request, if you created it correctly). If your request involves a mutation that modifies data and a subsequent query that reads it, the DataLoader’s per-request cache might serve stale data from before the mutation. Example: a resolver reads user A’s profile via userLoader.load("A"), which caches the result. Later in the same request (perhaps a complex mutation), user A’s profile is updated in the database. A subsequent userLoader.load("A") returns the cached (stale) version, not the updated one. The fix is to call userLoader.clear("A") after the mutation, which evicts that key from the cache. Alternatively, for mutations that you know will modify data, bypass the DataLoader and query the database directly. The DataLoader pattern is designed for read-heavy resolution within a single request, and mixing reads and writes within the same DataLoader requires careful cache invalidation.

4. Compare schema-first and code-first GraphQL development. You are starting a new federated API with five teams — which approach do you pick and why?

What the interviewer is really testing: Can you reason about developer workflow trade-offs at an organizational level, not just individual preference? Do you understand how the choice affects federation, cross-team collaboration, and long-term maintainability? Strong answer: For a federated API with five teams, I would choose schema-first. Here is my reasoning. The core difference: Schema-first means you write the SDL (.graphql files) as the source of truth, then implement resolvers that conform to it. Code-first means you write resolver code (using libraries like Nexus, Pothos, or gqlgen) and the schema is generated as a build artifact. Why schema-first for federation: The schema is the contract between teams. In a federated architecture, the Products team needs to know what fields the Reviews team is extending on Product. The Reviews team needs to know what @key fields are available. The frontend team needs to plan features against the schema before backend work starts. With schema-first, the SDL is a readable, diffable artifact that serves as the single source of truth for cross-team communication. You can review a schema change in a PR without understanding the implementation language of each subgraph. With code-first, the “schema” lives embedded in TypeScript or Go code. To understand what the Reviews subgraph exposes, you have to read the Reviews team’s code, in their language, with their framework’s abstractions. For a cross-team review, this is a barrier. The generated schema is a build output, not a first-class artifact — it exists only after the build runs. When code-first wins: For a single team building a non-federated API, code-first has a real advantage: type safety between your schema and implementation is guaranteed at compile time. With schema-first, the resolver and the schema can drift apart (you declare a field in SDL but forget to implement the resolver). Code-first makes that impossible. The hybrid middle ground: Some teams use schema-first for the SDL contract but generate resolver scaffolding from the schema (using graphql-codegen or similar). This gives you the readability of schema-first for cross-team collaboration and some of the type safety of code-first within each subgraph. My recommendation for the five-team setup: Schema-first SDL files checked into each subgraph’s repository, published to a schema registry (Apollo Studio or GraphQL Hive) on merge. Schema changes require a PR review that includes a member of the schema governance group. The registry validates composition on every push. Each team implements resolvers in whatever language and framework they prefer — the SDL is the contract, not the implementation.

Follow-up: How do you prevent the schema-first “drift” problem where the SDL and resolvers get out of sync?

Three mechanisms: 1. Integration tests that query every field. Write a test suite that sends an introspection query to the running subgraph, extracts every field from the introspected schema, and sends a query for each one. Any field that exists in the SDL but has no resolver will return an error. Run this in CI on every commit. 2. Code generation for resolver types. Use graphql-codegen to generate TypeScript interfaces for your resolvers from the SDL. If the SDL declares a Product.reviews field, the generated ProductResolvers interface requires a reviews method. Missing resolvers are compile-time errors. You still write the SDL first, but the resolver types are derived from it automatically. 3. Composition validation in CI. Apollo’s rover subgraph check validates that your subgraph schema is well-formed and composes with the supergraph. If you have a field in the SDL that references a type that does not exist or violates a federation rule, composition fails. This does not catch missing resolvers directly, but it catches structural inconsistencies. The combination of these three catches drift at compile time (codegen), integration time (tests), and composition time (registry checks).

Follow-up: What if the five teams use different backend languages — say, two use TypeScript, one uses Go, one uses Python, and one uses Java?

This is actually where schema-first shines the most. The SDL is language-agnostic. A .graphql file looks the same regardless of which language implements it. Each team picks the GraphQL library best suited to their language: Apollo Server for TypeScript, gqlgen for Go, Strawberry for Python, Netflix DGS for Java. They all implement the same SDL contract in their language’s idioms. With code-first, this would be nearly impossible. Each language’s code-first library has different abstractions for defining types, directives, and entities. There is no cross-language way to “review the schema” without generating the SDL first — at which point you have reinvented schema-first with an extra step. The federation gateway does not care what language each subgraph uses. It only sees the composed supergraph schema and the HTTP responses from each subgraph’s _entities resolver. This is one of federation’s biggest organizational wins: teams have language autonomy while presenting a unified API.

5. A client team complains that their GraphQL query returns correct data in staging but partially null data in production. The query has not changed. How do you debug this?

What the interviewer is really testing: Systematic debugging of a distributed system issue with partial failures — the kind of problem that separates senior engineers from mid-levels. Can you reason about why the same query behaves differently across environments? Strong answer: Partial nulls in GraphQL mean some resolvers succeeded and some failed. The errors array in the response is the first thing I look at — it tells me exactly which fields failed and why. But let me walk through the full diagnostic. Step 1: Get the actual response, including the errors array. The client team may be looking at data and not seeing the errors. GraphQL’s partial response model means data.order.items can be null while data.order.status is present — and the error explaining why items is null is in a separate errors array. Pull the full response body from logs or have the client reproduce with full response logging. Step 2: Identify the failing resolvers from the error paths. Each error has a path field (e.g., ["order", "items"]) that tells me exactly which resolver failed. The extensions.code tells me the category — INTERNAL_SERVER_ERROR, DOWNSTREAM_SERVICE_ERROR, FORBIDDEN, etc. Step 3: Check for environment-specific differences. The query works in staging but not production. Common culprits:

Data differences. The product in staging has 5 reviews; the product in production has 50,000. A resolver that works fine with 5 items might time out or hit a memory limit with 50,000. Check if the failing fields involve large data sets.
Authorization differences. Staging might use a permissive auth configuration (e.g., all fields accessible). Production has field-level auth. If the client’s token lacks a required scope or role, specific fields return FORBIDDEN nulls.
Downstream service health. The Reviews service might be healthy in staging but degraded in production. If the resolver for reviews calls a downstream service that is timing out, you get null with an error.
Missing DataLoader in production context. If the DataLoader is created conditionally or depends on a configuration that differs between environments, it might not batch correctly in production, causing timeouts.
Rate limiting. Production rate limits are stricter. The client’s query might exceed the cost budget in production but not staging (where limits are relaxed).

Step 4: Reproduce with tracing. If the above does not reveal the cause, enable Apollo Tracing or OpenTelemetry on the production request (or a production-like environment) and trace the exact query. Per-resolver timing will show where the failure occurs and how long the failing resolver ran before erroring. Step 5: Check if it is intermittent. “Works in staging, fails in production” could mean “fails intermittently in production.” A downstream service with occasional high latency, a database connection pool that is exhausted under production load, or a race condition that only manifests at production concurrency levels — these all produce intermittent partial nulls.

Follow-up: The error says “DOWNSTREAM_SERVICE_ERROR” on the `reviews` field. Staging and production both call the same Reviews microservice. What do you check next?

Even if they call the “same” service logically, the production and staging instances likely differ. I would check: Connection parameters: Production might have stricter timeouts. If the resolver has a 5-second timeout and the Reviews service occasionally takes 6 seconds under production load, you get intermittent failures. Staging, with less load, always responds in 2 seconds. Network topology: In production, the gateway might be in a different availability zone from the Reviews service, adding latency. Or a service mesh sidecar (Envoy, Istio) might be applying retry policies or circuit-breaking that differ from staging. Scale-dependent behavior: The Reviews service in production handles 100x the traffic of staging. If it is hitting database connection limits, memory pressure, or garbage collection pauses under load, it fails intermittently. Check the Reviews service’s own metrics — CPU, memory, database connection pool utilization, error rate. Data volume: The specific entities being queried in production might have significantly more reviews than those in staging. A product with 10,000 reviews might cause the Reviews service to OOM or exceed its response size limit, while the same query in staging against a product with 50 reviews succeeds. I would pull the Reviews service’s logs for the same time window, filtered by the request correlation ID (if you have distributed tracing), to see the error from the Reviews service’s perspective. The GraphQL layer knows the downstream call failed; the Reviews service’s logs tell you why.

Going Deeper: How do you build your GraphQL API so that partial failures like this degrade gracefully instead of confusing the client?

This is a schema design and client architecture question. On the schema side: Design nullable fields for anything that comes from a separate data source. If Product.reviews comes from the Reviews service, make it nullable (reviews: [Review!]). If the Reviews service is down, the product still renders with reviews: null. Never make a field non-nullable if its data source can fail independently — you will turn a partial failure into a total failure because GraphQL propagates null up to the nearest nullable parent. On the client side: Build components to handle null gracefully. The ProductPage component should render the product name and price even if reviews is null. Show a “Reviews unavailable” placeholder, not a full-page error. This is where GraphQL’s partial response model is a genuine advantage over REST — you get everything that worked and can render it. On the error handling side: Classify errors in a middleware layer. DOWNSTREAM_SERVICE_ERROR with extensions.serviceName: "reviews-service" gets a “This section is temporarily unavailable” treatment. UNAUTHENTICATED gets a redirect to login. RATE_LIMITED gets a retry-after. The client should never show a raw error message from the GraphQL response.

6. How would you implement cost-based rate limiting for a public GraphQL API from scratch? Walk through the algorithm.

What the interviewer is really testing: Can you design a non-trivial system that balances fairness, performance, and developer experience? Do you understand the unique challenge of GraphQL where every request has a different cost? Strong answer: Traditional rate limiting (100 requests/minute) is meaningless for GraphQL because { me { name } } and a deeply nested query requesting 10,000 nodes are both “one request.” Cost-based rate limiting charges each request proportional to its actual expense. The cost calculation algorithm: Each field in the schema has a base cost. Scalar fields cost 0 or 1. Object fields cost 1. List fields cost their base times the requested count. The total cost is the sum of all field costs in the query, with list multipliers applied recursively.

cost(field) = baseCost + childCost * multiplier

where:
  baseCost = defined per field (default 1 for objects, 0 for scalars)
  childCost = sum of cost(child) for all selected children
  multiplier = value of the pagination argument (first/last) for list fields, or 1 otherwise

For example, with this schema:

type Query {
  products(first: Int = 10): ProductConnection  # baseCost: 1
}
type Product {
  name: String           # cost: 0
  reviews(first: Int = 5): ReviewConnection  # baseCost: 1
}
type Review {
  rating: Int            # cost: 0
  author: User           # cost: 1
}

The query { products(first: 50) { edges { node { name reviews(first: 10) { edges { node { rating author { name } } } } } } } } costs:

products: 1 + (inner cost) * 50
Inner per product: name(0) + reviews(1 + inner * 10)
Inner per review: rating(0) + author(1 + 0)
Per review: 1 + 1 * 10 = 11… wait, let me be precise:
Per review: rating(0) + author(1) = 1
reviews per product: 1 + 1 * 10 = 11
Per product total: 0 + 11 = 11
products total: 1 + 11 * 50 = 551

So this query costs 551 units. The rate limiting mechanism: I would use a sliding window with token bucket approach (similar to Shopify’s leaky bucket):

Each API consumer gets a bucket that holds a maximum of (say) 2000 cost units
The bucket refills at a constant rate (say, 100 units per second)
Each request deducts its calculated cost from the bucket
If the bucket has insufficient units, the request is rejected with a 429-equivalent GraphQL error including retryAfter and current cost information

The beauty of the token bucket is that it allows bursts (a client can send an expensive query occasionally) while preventing sustained abuse (a client cannot continuously send expensive queries). Implementation detail: The cost is calculated before execution, during query validation. This is critical — you do not want to run an expensive query and then tell the client they exceeded their limit. The static cost analysis happens against the AST and schema, not against actual data, so it is fast (sub-millisecond). Developer experience: Return the cost information in every response, as GitHub and Shopify do:

{
  "extensions": {
    "cost": {
      "requestedQueryCost": 551,
      "actualQueryCost": 423,
      "throttleStatus": {
        "maximumAvailable": 2000,
        "currentlyAvailable": 1449,
        "restoreRate": 100
      }
    }
  }
}

Note the distinction between requestedQueryCost (the static estimate based on first arguments) and actualQueryCost (the real cost after execution — often lower because some lists return fewer items than requested). Charge based on the actual cost, but validate against the requested cost before execution.

Follow-up: What are the limitations of static cost analysis, and how do you handle them?

Static analysis uses the first/last pagination arguments to estimate list sizes. But it cannot know the actual cardinality of a list at analysis time. If a field returns a list without pagination (bad schema design, but it happens), the static analyzer has to use a default multiplier — say 100 — which might be wildly wrong in either direction. Also, the cost of a field might vary based on runtime conditions. A search(query: "a") might return 50,000 results while search(query: "xyzzy123") returns 3. The static cost is the same for both. To handle this, I would combine static analysis (pre-execution rejection for obviously expensive queries) with runtime cost tracking (measure the actual cost during execution and update the rate limit bucket post-execution). If the actual cost significantly exceeds the estimate, log it as a signal to adjust the field’s cost weight. Over time, the static estimates converge toward reality. For unbounded lists, the answer is: do not have them. Enforce pagination on every list field. This is both a performance and a rate limiting concern. If a list field lacks pagination, add a default limit (e.g., max 100 items) and enforce it in the resolver.

Follow-up: How does this interact with persisted queries? Can you skip cost analysis for known queries?

Yes, and this is a significant optimization. If you use persisted queries (where only pre-registered query hashes are allowed), you can pre-compute the cost of every registered query at registration time and store it alongside the hash. At runtime, when a client sends a hash, you look up the pre-computed cost instead of running the analysis on every request. This reduces the per-request overhead to a hash lookup plus a bucket check. The trade-off: if a query’s cost depends on variable values (e.g., products(first: $count)), you cannot fully pre-compute — you need to evaluate the cost formula with the provided variable values. But the formula itself (the structure of the cost tree) is pre-computed, so evaluation is just arithmetic. For public APIs where arbitrary queries are allowed, you cannot use this optimization. But for first-party clients using APQ (Automatic Persisted Queries), it is a significant win — especially at high request rates where the cost analysis computation itself becomes measurable.

7. Explain the difference between `@defer`, `@stream`, and subscriptions. When would you pick each, and what are the infrastructure implications?

What the interviewer is really testing: Understanding of incremental delivery mechanisms in GraphQL, the transport layer differences, and the ability to choose the right tool for the right problem. This separates people who have read about these features from people who have operated them. Strong answer: All three are mechanisms for delivering data to the client over time rather than in a single response, but they solve different problems and have very different operational characteristics. @defer delivers parts of a single query response incrementally. The server returns the non-deferred fields immediately, then streams the deferred fragment as a subsequent chunk over the same HTTP response (using multipart HTTP responses or chunked transfer encoding). The connection is short-lived — it opens, streams the chunks, and closes. Use case: a product page where the name and price resolve in 10ms from a fast cache, but reviews take 500ms from a slow microservice. With @defer, the client renders the product immediately and fills in reviews when they arrive. No second request needed. @stream is similar but for lists. Instead of waiting for all 100 items in a list to resolve, the server streams each item (or each batch of items) as they become available. Same transport as @defer — multipart responses over a single HTTP connection. Use case: a search results page where results come from multiple backends with different latencies. The first 5 results from the fast index arrive in 50ms; the next 20 from the slower secondary index arrive over the next 500ms. With @stream, the user sees results immediately and more appear progressively. Subscriptions maintain a persistent, bidirectional connection (WebSocket) between client and server. The client subscribes to an event, and the server pushes updates whenever that event occurs — potentially hours or days later. The connection stays open indefinitely. Use case: real-time notifications, live chat, collaborative editing, live sports scores — anything where the server needs to push data to the client at unpredictable times. Infrastructure implications are dramatically different:

@defer and @stream use standard HTTP infrastructure. They are stateless (each request is independent), work with load balancers, CDNs (with some caveats for streaming), and scale the same way your regular GraphQL endpoint does. The server just holds the response open slightly longer. Cost: minimal.
Subscriptions require WebSocket infrastructure. Each active subscription is an open TCP connection consuming memory and file descriptors on the server. They are stateful — the connection is pinned to a specific server instance, which means you need sticky sessions at the load balancer. Scaling to 100,000 concurrent subscriptions means 100,000 open connections. You need a pub/sub backend (Redis, Kafka) to broadcast events across server instances. Cost: significant.

Decision framework:

If you need to speed up the initial load of a single query: @defer / @stream
If you need the server to push updates after the initial query completes: subscriptions
If you are considering subscriptions but updates are infrequent (every 30+ seconds): polling is almost certainly simpler and cheaper

Follow-up: What is the current browser and tooling support for `@defer` and `@stream`?

As of mid-2025, @defer and @stream are still not finalized in the GraphQL spec — they are an RFC that has been in progress for several years. However, they have working implementations:

Apollo Client supports @defer since version 3.7. Apollo Router supports it on the gateway side.
Relay has experimental @defer support.
urql has community-contributed support.
Apollo Server and graphql-yoga support @defer and @stream via the graphql-js reference implementation.

The transport layer uses multipart HTTP responses (content-type: multipart/mixed). Most modern browsers handle this natively, but you need a GraphQL client that knows how to parse multipart responses and incrementally update the cache. The practical gotcha: not all CDNs and reverse proxies handle chunked/streaming HTTP responses well. Some will buffer the entire response before forwarding it, which defeats the purpose. You may need to configure your infrastructure layer (Nginx, Cloudflare, etc.) to disable response buffering for your GraphQL endpoint.

Follow-up: Can you use `@defer` in a federated setup? What complications arise?

Yes, but it adds complexity to the gateway’s query planning. When a deferred fragment includes fields from a different subgraph, the gateway must:

Execute the non-deferred portion (possibly across multiple subgraphs)
Return the initial response to the client
Execute the deferred portion (possibly requiring entity resolution across subgraphs)
Stream the deferred result as a subsequent chunk

The gateway must maintain state for the open response — it cannot be a purely stateless request-response proxy. Apollo Router supports this, but it means the gateway holds resources (memory, connection) for each in-flight deferred response until all chunks are delivered. The complication is when the deferred fragment depends on data from the non-deferred portion via @requires. The gateway has the data from step 1, but it needs to hold onto it until step 3. For long-running deferrals (e.g., a deferred field that calls a slow ML service), this increases the gateway’s memory footprint. At high concurrency, this can become a scaling concern.

8. You need to deprecate a widely-used field in your public GraphQL API. 2,000 third-party integrations reference it. Walk me through the process end to end.

What the interviewer is really testing: Communication, empathy for API consumers, operational discipline, and understanding that schema evolution is as much a people problem as a technical one. Strong answer: This is a multi-month process where the technical execution is straightforward but the human coordination is the hard part. Month 1: Analysis and announcement. First, understand the impact. Use field-level analytics to determine: how many distinct clients reference this field, how frequently, and for what operations. “2,000 integrations” is the total, but maybe 1,800 of them call it once a month and 200 call it millions of times a day. The heavy users need personal outreach; the light users need clear documentation. Announce the deprecation in three places: (1) the schema itself via @deprecated(reason: "Use 'priceV2' field instead. Will be removed on YYYY-MM-DD."), (2) the API changelog or developer blog, (3) direct email or notification to developers registered for API updates. Include the reason (why we are deprecating), the replacement (what to use instead, with code examples), and the timeline (when the field will stop working). Months 2-4: Migration support and monitoring. Publish a migration guide with before/after code examples in the most common languages your consumers use. If you have a developer relations team, have them create blog posts or videos. For the top 20 heaviest users, reach out directly — offer migration support, answer questions, and understand if the timeline works for them. Monitor the field’s usage weekly. Plot a graph of unique clients and request volume over time. Share this graph internally and in developer updates — “Usage has dropped from 2,000 to 1,200 integrations. Here is what is left.” Months 4-5: Warning responses. Before removing the field, add a warning in the response extensions:

{
  "extensions": {
    "deprecationWarnings": [
      {
        "field": "Product.price",
        "message": "This field will be removed on 2026-09-01. Use 'priceV2' instead.",
        "removalDate": "2026-09-01",
        "migrationGuide": "https://docs.example.com/migrate-price-field"
      }
    ]
  }
}

This is non-breaking — the field still works — but it surfaces the deprecation in the response itself, catching developers who missed the email and blog post. Month 6: Soft removal. Instead of hard-removing the field, change its resolver to return a stub value with a prominent error. For a price field, return 0 and include an error in the errors array with extensions.code: "DEPRECATED_FIELD" and a link to the migration guide. Log every request that hits the deprecated field so you can identify the remaining holdouts. Month 7+: Hard removal. Remove the field from the schema. Requests that reference it will fail with a validation error (“Cannot query field ‘price’ on type ‘Product’”). By this point, you should have near-zero usage based on your monitoring.

Follow-up: What if 50 integrations are still using the field at the deadline and refuse to migrate?

This is a business decision, not a technical one. Options: Extend the deadline. If the remaining 50 are significant partners or high-revenue integrations, extending by 2-3 months is pragmatic. Communicate the new deadline clearly and set a hard “no more extensions” date. Version the API. If the field cannot be removed without breaking critical partners, introduce a versioned schema. The current schema continues to serve the deprecated field for clients that explicitly request api-version: 2025-01. The new default schema does not include it. This is what Shopify does — they version their API quarterly and maintain previous versions for 12 months. Accept the breakage. For a public API with thousands of integrations, some breakage is inevitable. If 50 out of 2,000 have not migrated after 6 months of notice, direct outreach, and stub responses, the cost of maintaining the deprecated field indefinitely may exceed the cost of those 50 integrations experiencing a breakage. This is a judgment call that involves product, business, and engineering leadership. The key insight is to never surprise your consumers. If an integration breaks, it should be because they ignored months of warnings, not because you pulled the rug out without notice.

9. Your team is debating whether to use GraphQL subscriptions or polling for a live dashboard that shows order counts updating in near-real-time. Make the case for each side.

What the interviewer is really testing: Pragmatic engineering judgment. Can you argue both sides honestly, or are you a hammer looking for a nail? Do you understand the infrastructure cost of each approach? Strong answer: The case for polling: Polling means the client sends a regular GraphQL query every N seconds (say, every 5 seconds) and re-renders with the new data. Why it wins here: A dashboard showing order counts does not need sub-second latency. If the count updates every 5 seconds instead of instantly, no business decision is affected. Polling uses your existing HTTP infrastructure — no WebSockets, no sticky sessions, no pub/sub backend. Every request is stateless, load-balanced, and cacheable. If you have 500 dashboard users, that is 500 * (60/5) = 6,000 queries per minute — trivially handleable by any GraphQL server, and you can even cache the response for 5 seconds so all 500 users hit the cache. Operationally, polling is invisible. It uses the same monitoring, the same load balancers, the same error handling as every other query. When the server goes down, the next poll returns an error and the client shows “Data unavailable.” When it comes back, the next poll succeeds. No reconnection logic needed. The honest downside: If you poll every 5 seconds, the average staleness is 2.5 seconds and the maximum is 5 seconds. For a dashboard, this is fine. For a chat application, it is not. The case for subscriptions: Subscriptions mean the client opens a WebSocket, subscribes to orderCountChanged, and the server pushes updates the instant they happen. Why it might win: If the dashboard is mission-critical (war room during a flash sale, for example) and showing counts that are even 5 seconds stale could cause bad decisions (like turning off a promotion too late), subscriptions deliver updates in under 100ms. Subscriptions also eliminate wasted requests — with polling, 99% of polls return the same data because nothing changed. Subscriptions only send data when something actually changed. The honest downside: Subscriptions require WebSocket infrastructure. For 500 dashboard users, that is 500 persistent connections. Each connection is pinned to a server instance, so you need sticky sessions. You need a pub/sub layer (Redis) so that when the Orders service updates a count, the event reaches the server instance that has the subscriber. When the server restarts, all 500 connections drop and must reconnect — you need reconnection logic with backoff in the client. Your monitoring must track WebSocket connection health in addition to HTTP metrics. All of this for a feature where polling would have worked. My recommendation for this specific case: Start with polling at 5-second intervals. It is simpler by an order of magnitude and the user experience is indistinguishable from real-time for a dashboard use case. If product requirements change (e.g., the dashboard needs to show individual order events as they happen, not just counts), migrate to subscriptions at that point with a clear understanding of the infrastructure cost. The rule I follow: subscriptions are for when the user is waiting for something to happen (a chat message, a notification, a collaborative cursor). Polling is for when the user is looking at data that changes (dashboards, feeds, status pages). The distinction is subtle but drives the right infrastructure choice.

Follow-up: What about Server-Sent Events (SSE) as a middle ground?

SSE is a one-directional streaming protocol over HTTP. The server pushes events to the client, but the client cannot send messages back (unlike WebSockets). For GraphQL, you can implement subscriptions over SSE instead of WebSocket by streaming the subscription events as SSE messages. Advantages over WebSocket:

Uses standard HTTP, so it works with existing load balancers, proxies, and CDNs without special configuration
Automatic reconnection is built into the browser’s EventSource API
Simpler server implementation — no WebSocket upgrade handshake, no frame parsing
Works through corporate proxies that block WebSocket upgrades

Disadvantages:

One-directional only (server to client). For GraphQL subscriptions this is fine (the subscription query is sent via a normal HTTP request, and events are streamed back via SSE)
Limited to text data (no binary)
Browser limit of ~6 concurrent SSE connections per domain (in HTTP/1.1; HTTP/2 fixes this)

For the dashboard use case, SSE is arguably the best choice: it gives you push semantics (no wasted polling requests) with HTTP-compatible infrastructure (no sticky sessions, no WebSocket complexity). Libraries like graphql-sse implement the GraphQL-over-SSE protocol.

What the interviewer is really testing: Federation schema design skills, understanding of entity ownership, and organizational awareness. Can you navigate the political and technical challenges of shared types? Strong answer: This is the classic federation challenge: a core entity type that multiple domains want to extend. The answer is to use federation entities with a clear ownership model. Step 1: Designate a primary owner. The Identity team owns the User entity because they own the core identity data (ID, email, name, auth credentials). They define the entity with its @key:

# Identity subgraph (primary owner)
type User @key(fields: "id") {
  id: ID!
  email: String!
  displayName: String!
  avatarUrl: String
  createdAt: DateTime!
}

Step 2: Other teams extend the entity. The Social and Commerce teams contribute their domain-specific fields to User:

# Social subgraph
type User @key(fields: "id") {
  id: ID!
  friends(first: Int = 10, after: String): UserConnection!
  followers: FollowerConnection!
  posts(first: Int = 10, after: String): PostConnection!
}

# Commerce subgraph
type User @key(fields: "id") {
  id: ID!
  orders(first: Int = 10, after: String): OrderConnection!
  wishlist: [Product!]!
  defaultShippingAddress: Address
  loyaltyPoints: Int!
}

Each subgraph declares User with @key(fields: "id") and adds only the fields it owns. The gateway composes these into a single User type with all fields from all three subgraphs. Step 3: Establish field ownership rules. This is the governance part. The rules I would establish:

A field is owned by exactly one subgraph. If both Social and Commerce want a User.activityScore field, they must agree on which subgraph owns it, or create distinctly named fields (socialActivityScore, purchaseScore).
The primary owner (Identity) has veto power on changes to the @key fields. Changing the key definition affects every subgraph that references the entity.
New fields require composition validation in CI. Before any subgraph merges a change that adds fields to User, the CI pipeline runs composition and validates that there are no naming conflicts.

Step 4: Handle cross-subgraph field dependencies. If the Commerce subgraph’s loyaltyPoints calculation depends on the user’s createdAt (from Identity) to determine tier level:

# Commerce subgraph
type User @key(fields: "id") {
  id: ID!
  createdAt: DateTime @external
  loyaltyTier: LoyaltyTier! @requires(fields: "createdAt")
}

The @external marks createdAt as owned by another subgraph, and @requires tells the gateway to fetch createdAt from Identity before resolving loyaltyTier in Commerce.

Follow-up: What happens when two subgraphs accidentally define the same field on `User`?

Schema composition fails. Apollo’s composition engine detects that two subgraphs define User.activityScore (for example) and rejects the composition with an error like: “Field ‘User.activityScore’ is defined in both the Social and Commerce subgraphs. A field can only be defined in one subgraph.” This is the beauty of composition — it catches this conflict at build time, not at runtime. The fix is for the two teams to coordinate: either one team removes their field and delegates to the other, or they rename their fields to be distinct. If both teams legitimately need to provide the same field (same name, same semantics), they can use the @shareable directive in Federation v2, which explicitly allows multiple subgraphs to resolve the same field. The gateway will pick one (typically the first to respond). But @shareable should be used sparingly — it means multiple subgraphs can return different values for the same field, which can cause inconsistencies if their data sources disagree.

Follow-up: With three teams extending `User`, how do you manage schema reviews so that one team’s change does not break another’s?

Automated composition checks in CI. Every subgraph runs rover subgraph check against the production supergraph as part of its PR pipeline. If the Social team’s change breaks composition with the Commerce team’s current schema, the PR fails before merge. This is non-negotiable — it is the federation equivalent of a build check. Schema change proposals. For non-trivial changes (adding a new entity, changing a key, renaming a field), I would require a lightweight RFC process: a one-page document describing the change, its impact on other subgraphs, and the migration plan. The other teams review it asynchronously. This is not bureaucracy — it is communication scaled to the organization. Schema governance group. A rotating group of one representative from each team that reviews cross-subgraph changes weekly. They enforce naming conventions, pagination patterns, and error handling consistency across the supergraph. They also maintain a style guide (e.g., “all list fields use Relay connections, all mutations return a payload type with an errors field”). The organizational principle: federation decentralizes implementation but requires centralized governance of the contract. Each team can deploy their subgraph independently, but the schema — the contract between subgraphs and clients — must be reviewed collectively.

Advanced Interview Scenarios

These questions are designed to surface real production judgment. Several have “obvious” answers that are wrong. They reward engineers who have operated GraphQL at scale and been burned, not engineers who have only read the docs.

11. Your CDN cache hit rate for your GraphQL API is 2%. Your equivalent REST API had an 85% cache hit rate. Your VP of Engineering asks you to fix this. What do you do?

What weak candidates say: “GraphQL uses POST requests, so you just cannot cache it. That is the trade-off.” They accept the 2% as inherent to GraphQL and suggest adding a Redis layer behind the resolvers. They do not challenge the premise or explore the full solution space. What strong candidates say: The way I think about this is: GraphQL’s caching problem is not fundamental — it is a protocol mismatch that has well-known solutions at each layer. Layer 1: Move to GET requests with persisted queries. The biggest win. With Automatic Persisted Queries (APQ), the client sends a SHA-256 hash of the query as a GET request: GET /graphql?extensions={"persistedQuery":{"sha256Hash":"abc123"}}&variables={"id":"42"}. CDNs cache GET requests natively. At Shopify’s scale, this single change moved their cache-eligible traffic from effectively 0% to matchable with REST. The key is that the hash + variables combination produces a stable, deterministic URL that the CDN treats exactly like a REST endpoint. Layer 2: Field-level cache control directives. Not all data is cacheable. A Product.name can be cached for hours; a Product.inventoryCount changes every second. Apollo Server’s @cacheControl(maxAge: 3600) directive lets you set TTLs per field. The server-side cache calculates the effective TTL as the minimum across all fields in the response. If the client queries name (1 hour TTL) and inventoryCount (0 TTL), the response is uncacheable. This is where schema design matters: separate volatile fields into a different query or use @defer so the cacheable portion can be served from CDN while the volatile part is fetched fresh. Layer 3: Normalized server-side response cache. Tools like @stellate/graphql-cache (formerly GraphCDN) or Apollo Router’s response cache understand the GraphQL operation structure. They cache not just by URL but by operation hash + variable combination + auth context. When a mutation invalidates an entity, these caches can purge all cached responses that reference that entity. This is dramatically more sophisticated than a dumb HTTP cache and is what gets you from 50% to 85%+ hit rates. Layer 4: Client-side normalized cache. Apollo Client’s InMemoryCache stores entities by __typename:id. If two different queries both fetch Product:42, the client stores one copy and serves both from cache. This is unique to GraphQL — REST clients cache by URL, so the same product fetched from /products/42 and /featured-products is cached twice. The counterintuitive insight: A well-tuned GraphQL caching stack can actually exceed REST’s cache hit rate because the normalized client cache deduplicates across operations in a way REST cannot. The 2% hit rate is a configuration problem, not a technology problem. War Story: At a company I worked with processing 40M GraphQL requests/day, we went from 3% CDN hit rate to 72% in two weeks by deploying APQ with GET requests and splitting our most popular query into a cacheable “shell” query (product name, images, description — all with 30-minute TTLs) and a volatile “live data” query (price, inventory, ratings — fetched fresh). The shell query served from CDN at the edge in 15ms. Total page load improved from 800ms to 200ms for repeat visitors. The trick nobody tells you: restructuring your queries for cacheability is more impactful than any cache infrastructure you deploy.

Follow-up: How do you handle cache invalidation when a mutation changes data that is referenced in hundreds of cached responses?

What strong candidates say: This is the hard part. Three approaches in order of sophistication: Tag-based invalidation. When caching a response that includes Product:42, tag the cache entry with product:42. When a mutation updates product 42, purge all entries tagged with product:42. Stellate and Fastly VCL both support this. The challenge is maintaining the tag index at scale — with millions of cached entries and thousands of tags, the tag lookup itself becomes a performance concern. In practice, you shard the tag index by entity type and use Redis sets for O(1) tag membership checks. TTL-based eventual consistency. For many use cases, stale data for 30-60 seconds is acceptable. Set conservative TTLs and let the cache expire naturally. No invalidation logic needed. The art is knowing which fields can tolerate staleness (product descriptions, user profiles) and which cannot (inventory counts, prices). This is the 80/20 solution — it gets you most of the cache benefit with none of the invalidation complexity. Hybrid. TTL for most fields, tag-based invalidation for business-critical fields. Product name changes? TTL expiry in 30 minutes is fine. Price changes during a flash sale? Purge immediately via tag.

Follow-up: Does Apollo Client’s normalized cache solve the invalidation problem on the client side?

Partially. Apollo Client’s InMemoryCache automatically updates any cached query that references an entity when a mutation returns that entity with updated fields. If your updateProduct mutation returns the full Product object, every query displaying that product updates instantly in the UI. But this only works within a single browser session. Other users still see stale data until their client fetches fresh data. And it only works if the mutation result includes all the fields the cached queries reference — if the mutation returns only { id, name } but a cached query also displays price, the price remains stale. The discipline is: always return every field in the mutation response that any UI component might display. Or use refetchQueries to explicitly re-fetch affected queries after a mutation, which is heavier but guarantees consistency.

12. Your federated GraphQL gateway is a single point of failure. At 3 AM, the gateway goes down and every frontend is dead. How do you make the gateway resilient, and what is the obvious solution that actually makes things worse?

What weak candidates say: “Just add more gateway instances behind a load balancer.” While horizontal scaling is part of the answer, they stop there. They do not address query plan caching, supergraph schema availability, or the subtler failure mode where the gateway is up but the schema registry is down. What strong candidates say: The gateway is the single fan-in point for all client traffic, so its availability directly determines your API’s availability. Here is how I layer resilience, starting with the mistakes I have seen teams make: The obvious solution that backfires: aggressive retry logic in the gateway. When a subgraph is slow, the instinct is to add retries. But if the Orders subgraph takes 5 seconds to respond and the gateway retries 3 times with 2-second timeouts, each client request now takes 6 seconds and generates 3x the load on the already-struggling subgraph. You have amplified the failure. Instead, use circuit breakers: after N consecutive failures to a subgraph, the gateway stops calling it for a cooldown period and returns null for fields owned by that subgraph. The rest of the query still resolves. Apollo Router supports this natively. I configure a 50% error rate threshold over a 10-second window to trip the circuit, with a 30-second cooldown and 5-request half-open probe. Supergraph schema availability. The gateway needs the supergraph schema to plan queries. If it fetches the schema from Apollo Studio (or your schema registry) on startup and the registry is down, the gateway cannot start. Fix: bake the supergraph schema into the gateway’s deployment artifact. Apollo Router supports loading the schema from a local file. Your CI pipeline fetches the latest composed supergraph, bundles it into the Docker image, and deploys. The gateway starts with the bundled schema and optionally polls for updates. If the registry is down, the gateway runs on the last-known-good schema. Never make your critical data path depend on an external SaaS for startup. Query plan caching. Query planning is CPU-intensive. For a federated supergraph with 15+ subgraphs, planning a complex operation can take 10-50ms. Apollo Router caches query plans in memory, keyed by operation hash. For APIs with persisted queries, the plan cache is bounded and predictable. For APIs accepting arbitrary queries, the plan cache can grow unbounded — set a max cache size and evict LRU. The plan cache must survive gateway restarts; some teams persist it to Redis or a local file so a new instance starts warm. Graceful degradation at the gateway. When one subgraph is down, the gateway should still serve fields from healthy subgraphs. This requires the schema to be designed with nullable fields for cross-subgraph data. If Product.reviews comes from the Reviews subgraph and that subgraph is down, reviews returns null with a DOWNSTREAM_SERVICE_ERROR in the errors array. The client renders the product without reviews. If you made reviews: [Review!]! (non-nullable), a failure in the Reviews subgraph propagates null up to the nearest nullable parent — potentially nulling out the entire product field. Non-nullable fields in a federated schema are a reliability hazard. Every field sourced from a different subgraph should be nullable. War Story: A fintech I consulted for had their Apollo Gateway (Node.js) crash at 3 AM because a subgraph team deployed a schema change that tripled the supergraph size. The query planner’s memory usage spiked, Node’s heap limit was hit, and the process OOMed. All 3 gateway instances crashed within seconds of each other because they all polled the schema registry at the same interval and got the new schema simultaneously. The fix was three-fold: (1) migrate to Apollo Router (Rust, no GC-based OOM), (2) stagger schema poll intervals across instances so they do not all update simultaneously, (3) add a schema size regression test in CI that fails if the composed supergraph exceeds a threshold. Total downtime: 47 minutes. Revenue impact: ~$200K. The root cause was not the schema change — it was the lack of guardrails around supergraph growth.

Follow-up: How do you test gateway resilience before an outage teaches you the hard way?

What strong candidates say: Chaos engineering, specifically targeted at the federation layer. Subgraph fault injection. Use a service mesh sidecar (Envoy, Istio) to inject latency or errors into subgraph responses. Verify that the gateway returns partial results with appropriate errors instead of timing out entirely. Run this weekly in a staging environment against your top 10 operations. Schema bomb testing. Deploy intentionally large or deeply nested subgraph schemas in a test environment and verify the gateway handles composition and query planning within resource limits. This catches the OOM scenario I described. Load testing with realistic operation mix. Most load tests send one operation repeatedly. Real traffic is a mix of cheap and expensive operations. Record production traffic (operation hashes + variable distributions) and replay it against a staging gateway. This reveals performance cliffs that single-operation load tests miss.

Follow-up: What is the availability target you would set for the gateway, and how does it differ from individual subgraph SLOs?

The gateway’s availability must be at least as high as the highest SLO of any subgraph it fronts. If the Orders subgraph promises 99.99% (52 minutes downtime/year), the gateway must also be 99.99% or better — otherwise the gateway is the bottleneck. In practice, the gateway should target one 9 higher than the highest subgraph SLO. If subgraphs target 99.9%, the gateway targets 99.99%. The reason: each subgraph failure only affects queries that touch that subgraph (partial failure). A gateway failure affects all queries (total failure). The blast radius difference justifies the higher target. This has budget implications. A 99.99% SLO means 52 minutes of downtime per year. That means: no single-region deployments (one AZ failure eats your annual budget), no dependency on external services for the hot path (schema registry, APM, feature flags — all must be pre-fetched or cached), and an on-call rotation that can respond within 5 minutes.

13. A mutation in your GraphQL API needs to update an order (Orders subgraph), deduct inventory (Inventory subgraph), and charge the customer (Payments subgraph). How do you handle the case where Payments succeeds but Inventory fails? Most candidates get this wrong.

What weak candidates say: “Use a distributed transaction across the subgraphs” or “The gateway should coordinate a two-phase commit.” This is the answer that sounds right but is almost never correct in a microservices architecture. Two-phase commit across HTTP services is fragile, slow, and not supported by any GraphQL gateway. What strong candidates say: The key insight that most people miss: GraphQL federation does not give you distributed transactions, and you should not try to build them. The gateway orchestrates queries across subgraphs, not transactions. Each subgraph call is an independent HTTP request. There is no shared transaction context, no rollback mechanism, and no atomicity guarantee across subgraphs. The right approach is the Saga pattern. Instead of one atomic transaction, you decompose the operation into a sequence of local transactions, each with a compensating action:

Create order in PENDING state (Orders subgraph) — compensating action: mark order as FAILED
Reserve inventory (Inventory subgraph) — compensating action: release reservation
Charge payment (Payments subgraph) — compensating action: issue refund
Confirm order (Orders subgraph) — mark as CONFIRMED

If step 3 (payment) succeeds but step 2 (inventory) failed, the saga coordinator triggers the compensating action for step 3: issue a refund. The order is marked FAILED with a reason. Where the mutation resolver lives: The placeOrder mutation should live in one subgraph (typically Orders, since it is the orchestrator). This resolver does NOT call other subgraphs via GraphQL. It publishes events to a message broker (Kafka, SQS, or an internal event bus), and the Inventory and Payments services subscribe to those events and publish their results back. The orchestrator tracks the saga state and triggers compensations on failure. The critical mistake: Trying to make the GraphQL mutation resolver synchronously call the Inventory and Payments subgraphs as REST/gRPC calls and “roll back” on failure. This creates tight coupling between subgraphs (defeating the purpose of federation), introduces cascading failure risk (if Payments is slow, the entire mutation hangs), and has no reliable rollback mechanism (what if the rollback call to Payments also fails?). What the client sees: The mutation returns immediately with { order: { id: "123", status: PENDING }, errors: [] }. The client polls or subscribes to orderStatusChanged to learn the final outcome. This is eventually consistent, which is the correct model for a multi-service operation. War Story: An e-commerce platform I worked on tried the “synchronous cross-subgraph mutation” approach for their checkout flow. The placeOrder resolver called Inventory (gRPC, 200ms), then Payments (REST, 800ms), then Shipping (REST, 300ms) — all sequentially in one resolver. Total mutation latency: 1.3 seconds on the happy path. On Black Friday, the Payments service latency spiked to 5 seconds. The resolver timed out after 10 seconds, but the payment had already been charged. The “rollback” code issued a refund, but the refund call also timed out because the Payments service was overwhelmed. Result: 340 customers were charged without receiving orders. We spent the next 48 hours doing manual reconciliation. The fix was migrating to an event-driven saga with Kafka. Mutation latency dropped to 50ms (just creating the order in PENDING state), and the saga handled the rest asynchronously with guaranteed at-least-once delivery and idempotent compensations.

Follow-up: How does the client know when the saga completes, given the mutation returns immediately with PENDING?

Three options, in order of complexity: Polling. The client receives the order ID from the mutation response and polls { order(id: "123") { status } } every 2-3 seconds. Simple, stateless, works with existing infrastructure. For checkout flows where the saga completes in 2-10 seconds, this is pragmatic. Subscriptions. The client subscribes to orderStatusChanged(orderId: "123") and receives a push when the saga reaches a terminal state (CONFIRMED or FAILED). Lower latency, no wasted polls. But requires WebSocket infrastructure. Optimistic UI with reconciliation. The client shows “Order placed!” immediately after the mutation returns PENDING, based on the assumption that most sagas succeed. If the saga fails (notification arrives via poll or subscription), the UI updates to “There was a problem with your order” and presents recovery options. This gives the best perceived performance because the user sees success instantly. Amazon uses this pattern — you see “Order confirmed” immediately, and the rare failure is communicated via email.

Follow-up: What if the saga takes 30 seconds because the Payments provider is slow? The user is staring at a spinner.

This is a UX problem, not a technical one. The mutation itself should return in under 100ms (just creating the PENDING order). The spinner the user sees is the client waiting for the saga to complete, not the mutation blocking. The fix is to not make the user wait. Return to a confirmation page immediately: “Your order has been placed. You will receive a confirmation email shortly.” Show the order in PENDING state in their order history. If the saga completes while they are still on the page, update in real-time via subscription or poll. If they navigate away, send the confirmation or failure via email/push notification. The anti-pattern is keeping the client blocked on a single mutation call that internally waits for the entire saga. That couples the user’s experience to the slowest service in the chain.

14. You are seeing intermittent “out of memory” crashes on your GraphQL server. They happen roughly once a day under normal traffic. How do you find the leak, and what are the GraphQL-specific causes most engineers miss?

What weak candidates say: “Add more memory to the servers” or “It is probably a DataLoader caching issue — just clear the cache.” They jump to solutions without a diagnostic methodology. They do not mention profiling tools or GraphQL-specific leak vectors. What strong candidates say: Memory leaks in GraphQL servers have a distinctive signature compared to generic Node.js leaks because the GraphQL execution model creates unique allocation patterns. Here is my diagnostic approach: Step 1: Confirm it is a leak, not a spike. Pull the memory usage graph from Prometheus/Datadog over 72 hours. A true leak shows a sawtooth pattern: memory gradually climbs over hours, the process OOMs, restarts, and the climb starts again. A spike-and-recovery pattern (memory jumps during traffic peaks, returns to baseline) is not a leak — it is normal GC behavior or an undersized heap. Step 2: Identify the allocation source. Take heap snapshots at 3 points: at startup, after 1 hour, and after 6 hours. Compare them using Chrome DevTools (connect via --inspect flag) or clinic.js. Look for object types whose count grows between snapshots but never shrinks. Common findings in GraphQL servers: GraphQL-specific cause 1: Global DataLoader instances. If someone accidentally created DataLoaders at the module level instead of per-request, every request’s results accumulate in the DataLoader’s internal cache. After 100K requests, you have 100K cached result sets in memory. This is the single most common GraphQL memory leak I have seen. The fix: verify DataLoaders are created in context() factory, not imported from a shared module. Grep the codebase for new DataLoader and verify every instance is inside a function that runs per-request. GraphQL-specific cause 2: Unbounded query plan cache. If you are using Apollo Gateway or a custom gateway, query plans are cached in memory keyed by operation string. With persisted queries, this cache is bounded by the number of registered operations. With arbitrary queries (public API), every unique query string adds a new plan to the cache. A client sending queries with random aliases ({ a1: product(id: "1") { name } }, { a2: product(id: "1") { name } }) creates unbounded cache growth. The fix: set a max cache size with LRU eviction. Apollo Router handles this by default; custom implementations must add it manually. GraphQL-specific cause 3: Subscription connection state. Each active subscription holds a reference to its iterator, filter function, and client context. If subscriptions are not properly torn down on client disconnect (common when WebSocket disconnects are not detected promptly — e.g., a mobile app going to background without closing the socket), the server accumulates orphaned subscription objects. The fix: implement heartbeat/ping-pong on WebSocket connections with a 30-second timeout. If a client misses 2 heartbeats, force-close the connection and clean up the subscription. The graphql-ws library handles this, but the deprecated subscriptions-transport-ws does not, which is one reason the community moved away from it. GraphQL-specific cause 4: Large response buffering. If a resolver returns a massive result (e.g., a list of 50,000 items because pagination was not enforced), the entire response is buffered in memory before being serialized to JSON and sent to the client. Ten concurrent requests like this and you have exhausted your heap. The fix: enforce maxItems limits in every list resolver, and implement response size limits at the server level. Apollo Server’s maxResponseSize plugin or a custom middleware that tracks response size during serialization and aborts if it exceeds a threshold (e.g., 10MB). Step 3: Reproduce under controlled conditions. Once you have a hypothesis, write a load test that targets the suspected cause. For DataLoader leaks: send 10,000 unique queries and monitor heap growth. For subscription leaks: open 1,000 connections, kill the client process without cleanly closing sockets, and verify the server cleans up within the heartbeat timeout. War Story: A media company running GraphQL for their content API had daily OOMs at exactly 2 PM. Traffic at 2 PM was no higher than noon. The heap snapshot revealed 4 million cached entries in what turned out to be a query plan cache. The root cause: their React app used a GraphQL code generator that included a timestamp comment in every query string (# Generated at 2026-04-10T14:00:00). Every minute produced a “new” operation from the cache’s perspective, and the plan cache grew without bounds. The timestamp had been added by a junior developer for debugging and never removed. We found it by diffing two cached query plans that should have been identical and spotting the comment. Fix: strip comments from incoming queries before cache lookup (Apollo Router does this automatically; their custom Node.js gateway did not). Total time to diagnose: 6 hours. Total time to fix: 20 minutes. The lesson: the weirdest bugs come from the smallest details.

Follow-up: How do you prevent memory leaks from recurring? What guardrails do you put in place?

Production guardrails:

Memory-based auto-restart. Configure your container orchestrator (Kubernetes) to restart the pod when memory exceeds 80% of the limit. This is not a fix — it is a safety net that prevents OOM kills from affecting availability. Use resources.limits.memory in K8s and ensure the container runs a single process so the OOM killer targets the right thing.
Heap usage alerting. Alert when the memory growth rate (MB/hour) exceeds a threshold. A healthy server’s memory should plateau. If it grows linearly for 2+ hours, something is leaking.
Canary deployments with memory regression checks. When deploying a new version, compare the canary’s memory profile against the stable version over 1 hour. If the canary’s memory growth rate is 2x or higher, roll back automatically.

Development guardrails:

Lint rule: no module-level DataLoader instantiation. A custom ESLint rule that flags new DataLoader() calls outside of a function body.
Integration test: memory stability under load. Run 10,000 GraphQL operations against a test server and assert that heap usage after a forced GC is within 20% of the starting heap. This catches gross leaks before deployment.

15. Your team wants to add GraphQL to an existing system that uses gRPC for all inter-service communication. A senior architect says “GraphQL is redundant — gRPC already solves the same problems.” How do you respond?

What weak candidates say: “GraphQL is better than gRPC because clients can choose their data” or “gRPC is for backend, GraphQL is for frontend” — surface-level statements without depth on why or when the distinction matters. They cannot articulate the complementary nature of the two technologies. What strong candidates say: The architect is both right and wrong, and the nuance matters. gRPC and GraphQL operate at different layers of the stack and solve different problems. They are not competing — they are complementary in most architectures. What gRPC solves: Strongly-typed, high-performance, bidirectional streaming communication between backend services. Protobuf serialization is 3-10x smaller than JSON. HTTP/2 multiplexing eliminates head-of-line blocking. Code generation produces client and server stubs in any language. Service-to-service latency at companies like Google, Netflix, and Uber is dominated by gRPC because it is the fastest practical RPC framework. What gRPC does NOT solve: Frontend data aggregation. A mobile app rendering a product page needs data from the Product service, Reviews service, Inventory service, and User service. With gRPC alone, the client either: (a) makes 4 separate gRPC calls (which means the mobile app needs gRPC client libraries, handles 4 response types, and manages 4 error paths), or (b) calls a BFF (Backend for Frontend) that aggregates the 4 calls and returns a bespoke response (which is REST-with-extra-steps and creates a coupling bottleneck). What GraphQL adds: A single, typed, client-driven entry point that aggregates data from backend services. The GraphQL server sits at the API edge. Internally, its resolvers call backend services via gRPC. The mobile client sends one GraphQL query and gets exactly the shape it needs. The web client sends a different query and gets a different shape. Neither client knows or cares that the backend is gRPC. The architecture:

Mobile/Web Client --[GraphQL]--> API Gateway --[gRPC]--> Product Service
                                             --[gRPC]--> Reviews Service
                                             --[gRPC]--> Inventory Service

Where the architect is right: If the “client” is another backend service, GraphQL adds no value. Service A calling Service B should use gRPC directly — it is faster, more efficient, and has built-in streaming. Putting GraphQL between two backend services is adding latency and complexity for no benefit. Where the architect is wrong: If the client is a browser or mobile app, gRPC is impractical. gRPC-Web exists but it is limited (no bidirectional streaming, requires a proxy), has poor browser support for the full feature set, and no ecosystem of UI-focused tooling (no equivalent of Apollo DevTools, no normalized client cache, no fragment colocation). GraphQL was designed for exactly this problem space. The nuanced answer I would give the architect: “You are right that gRPC solves inter-service communication better than GraphQL. I am not proposing we replace gRPC. I am proposing we add GraphQL as the frontend aggregation layer. Our GraphQL resolvers will call your gRPC services — you get to keep your protobufs, your streaming, and your performance. The frontend team gets a single typed API that they can query without coordinating with five backend teams for every screen change. The two technologies are complementary.” War Story: Netflix runs one of the most sophisticated examples of this architecture. Their backend services communicate via gRPC. Their Studio applications (the tools Netflix employees use to manage content) are built on a federated GraphQL API where resolvers call gRPC services. When Netflix’s DGS framework (their Java-based GraphQL server) resolves a field, it calls the owning gRPC service via a generated client stub. The frontend team iterates on queries without backend changes. The backend team evolves protobufs without frontend coordination. The GraphQL schema is the contract between the two worlds. This is the architecture I would propose.

Follow-up: What about gRPC-Web? Does not that solve the frontend problem directly?

gRPC-Web is a protocol adaptation that lets browser clients call gRPC services via a proxy (Envoy, typically). It works, but with significant limitations:

No client-streaming or bidirectional streaming. Only unary calls and server-streaming. This eliminates gRPC’s biggest advantage for real-time features.
Requires a proxy. The browser cannot speak native gRPC (no HTTP/2 trailer support in browser fetch). You need Envoy or a similar proxy translating gRPC-Web to native gRPC. This is another infrastructure component to maintain.
No data aggregation. The client still makes separate calls to each service. There is no “query” concept that fetches data from multiple services in one request. Each gRPC-Web call is one service, one method, one response.
No client ecosystem. No normalized caching, no dev tools, no fragment colocation, no query complexity analysis. You are hand-rolling everything that Apollo Client or Relay provides for free.

gRPC-Web is a reasonable choice when: you have a single backend service, the frontend team is comfortable with protobuf types, and you do not need data aggregation. For a microservices architecture where the frontend needs data from 5+ services, GraphQL over gRPC backends is the more practical architecture.

Follow-up: How do you handle the schema mapping between GraphQL types and Protobuf messages?

This is a real operational concern. Your GraphQL Product type and your Protobuf Product message will have overlapping but not identical fields. The resolver layer is the translation layer:

// GraphQL resolver that calls a gRPC service
const resolvers = {
  Query: {
    product: async (_, { id }, { grpcClients }) => {
      const proto = await grpcClients.products.getProduct({ id });
      return {
        id: proto.id,
        name: proto.name,
        price: proto.priceInCents / 100, // Protobuf uses integer cents
        createdAt: proto.createdAt.toDate(), // Protobuf Timestamp to JS Date
      };
    },
  },
};

At scale, you do not write these mappings by hand. Tools like graphql-codegen with custom plugins can generate resolver scaffolding from protobuf definitions. Alternatively, GraphQL Mesh can auto-generate a GraphQL schema from protobuf definitions and handle the translation automatically. Netflix’s DGS framework has built-in protobuf-to-GraphQL mapping for this reason. The discipline is: the GraphQL schema is designed for the frontend’s needs, not as a 1:1 mirror of the protobuf definitions. Field names, nesting, and even data types may differ. The resolver layer absorbs this impedance mismatch.

16. An intern shows you a GraphQL schema they designed where every query returns a `Result` union type: `union Result = SuccessPayload | ErrorPayload`. Every single query uses this pattern. Is this good design? The answer is not what most people think.

What weak candidates say: “Yes, this is great! It makes error handling explicit and type-safe everywhere.” They have read one blog post about the “Result type pattern” and apply it universally without understanding the trade-offs. What strong candidates say: This is a case where a good pattern applied universally becomes an anti-pattern. The intern has taken the mutation result type pattern (which IS good practice for mutations) and over-applied it to queries. Here is why that is a problem: For mutations, the Result union is excellent. Mutations have expected failure modes that clients need to handle: validation errors, permission issues, conflict states. union PlaceOrderResult = OrderSuccess | OutOfStockError | PaymentDeclinedError is self-documenting, type-safe, and forces the client to handle each case. Shopify and GitHub both use this pattern. It is a proven best practice. For queries, the Result union fights against GraphQL’s built-in error model. GraphQL already has a first-class mechanism for query errors: the errors array with partial data. If { product(id: "42") { name price reviews } } fails to fetch reviews, GraphQL returns { data: { product: { name: "Widget", price: 29.99, reviews: null } }, errors: [{ path: ["product", "reviews"], ... }] }. The client gets the data that worked AND the error signal. This is partial success — GraphQL’s killer feature. With the intern’s pattern, the query returns union GetProductResult = Product | NotFoundError | InternalError. If the product resolver succeeds but the reviews resolver fails, the entire result must be either success or error — you lose partial data. The client gets nothing useful instead of getting name and price with a null reviews field. You have recreated REST’s all-or-nothing error model inside GraphQL. The deeper problem: composition. In a federated architecture, a query might traverse 5 subgraphs. With GraphQL’s native error model, each subgraph can fail independently, and the client gets partial results from the healthy subgraphs. With union-based error handling on queries, the gateway has to decide: is the overall result a “success” or an “error”? If 4 out of 5 subgraphs succeeded, which union variant do you return? This question has no good answer because the pattern was not designed for distributed partial failure. My guidance to the intern: Keep the Result union pattern for mutations — it is excellent there. For queries, use GraphQL’s built-in error model: nullable fields for anything that can fail independently, structured errors in the errors array with extensions.code, and client-side error classification. The two error handling models serve different purposes and should not be unified. The exception: There is one query-level case where a union return IS appropriate: when the type of the successful result varies. union SearchResult = Product | Article | User is not an error handling pattern — it is a type discrimination pattern, and it is the right tool for that job. War Story: A startup I advised had adopted the “everything returns a Result union” pattern from a conference talk. Their GetUser query returned union GetUserResult = User | NotFoundError | ForbiddenError. Looks clean. But when they added field-level authorization (some users can see email, others cannot), they had a problem: the user exists (not a NotFoundError), the caller is authorized to see the user (not a ForbiddenError), but they are NOT authorized to see the email field specifically. With the union pattern, they had no way to return a User with some fields null-for-auth-reasons and some fields populated. They had to add another union variant: PartialUser. Then PartialUserWithSomeFields. The type hierarchy spiraled. They eventually ripped out the query-level unions and switched to GraphQL’s native nullable-fields-with-errors model. The migration took 3 weeks and touched every frontend component. The lesson: do not fight the framework’s built-in error model.

Follow-up: How do you design the mutation result type pattern correctly? What are the subtle mistakes?

Three common mistakes I see: Mistake 1: Putting the success type and error types in the same union without a common interface. The client has to use __typename switching, which is fine, but you should add an interface for common error fields:

interface UserError {
  message: String!
  code: ErrorCode!
}

type ValidationError implements UserError {
  message: String!
  code: ErrorCode!
  field: String!  # Which input field caused the error
}

type OutOfStockError implements UserError {
  message: String!
  code: ErrorCode!
  productId: ID!
  availableQuantity: Int!
}

This lets clients handle all errors generically (if result implements UserError, show message) while still handling specific errors with rich data. Mistake 2: Not including the mutated entity in error payloads when relevant. If updateProduct returns a ValidationError, should the error include the current state of the product? Often yes — the client needs to know the current state to show the user what went wrong. Include a nullable entity reference: type ValidationError implements UserError { ..., product: Product }. Mistake 3: Using string error messages as the error contract. Clients parse message: "Email already taken" to determine the error type. This is fragile — if someone changes the message to “This email is already in use,” the client breaks. Always include a machine-readable code enum that the client switches on. The message is for humans (display or logging); the code is for machines (conditional logic).

17. You join a team and discover their GraphQL API has zero observability — no operation-level metrics, no field-level tracing, no error rate dashboards. HTTP monitoring shows 100% success rate. What do you build first, and what will you discover?

What weak candidates say: “Set up Datadog and add some dashboards.” They treat it as a generic monitoring setup and do not address the GraphQL-specific blindness caused by HTTP 200. What strong candidates say: This is one of the most common and dangerous states for a GraphQL API to be in. The HTTP 200 success rate is a lie — every GraphQL response returns 200, even when the errors array is full of failures. The team literally cannot see their own error rate. Here is what I build, in order of impact: Day 1: GraphQL-aware error rate metric. This is the single highest-value thing you can add. Write a middleware plugin (Apollo Server plugin, Yoga plugin, or Express middleware) that inspects every response:

const metricsPlugin = {
  requestDidStart() {
    return {
      willSendResponse({ response, request }) {
        const operationName = request.operationName || 'anonymous';
        const hasErrors = response.body?.singleResult?.errors?.length > 0;
        
        metrics.increment('graphql.requests.total', {
          operation: operationName,
          status: hasErrors ? 'error' : 'success',
        });
        
        if (hasErrors) {
          for (const error of response.body.singleResult.errors) {
            metrics.increment('graphql.errors', {
              operation: operationName,
              code: error.extensions?.code || 'UNKNOWN',
              path: error.path?.join('.') || 'unknown',
            });
          }
        }
      },
    };
  },
};

Export to Prometheus. Build a Grafana dashboard with: (1) request rate by operation, (2) error rate by operation and error code, (3) error rate as a percentage of total requests. I guarantee you will discover an error rate between 5-15% that nobody knew about. Common findings: INTERNAL_SERVER_ERROR from unhandled promise rejections in resolvers, FORBIDDEN errors from misconfigured auth on certain fields, DOWNSTREAM_SERVICE_ERROR from one flaky microservice. Week 1: Operation-level latency histograms. Add latency tracking per named operation: P50, P95, P99. GraphQL operations have wildly different latency profiles — GetUserProfile (50ms) vs SearchProducts (800ms) vs GetDashboardData (3 seconds). An aggregate latency metric is meaningless. Per-operation metrics let you set SLOs per operation and alert when specific operations degrade. Week 2: Resolver-level tracing. Enable OpenTelemetry or Apollo Tracing to capture per-resolver execution time. This reveals N+1 problems (a resolver called 500 times at 2ms each = 1 second hidden in parallel execution), slow downstream calls (one resolver takes 2 seconds because the service it calls is slow), and authorization overhead (auth checks adding 50ms per resolver, compounding in deep queries). Week 3: Field usage analytics. Track which fields are requested, by which operations, and how often. This data is not about performance — it is about schema evolution. You cannot safely deprecate fields without knowing who uses them. You cannot prioritize optimization without knowing which fields are hot. Export field usage to a time-series database and build a “field popularity” dashboard. This also reveals dead schema — fields that nobody has requested in 90 days. At one company, 30% of the schema was unused, maintained by engineers who assumed “someone must be using it.” What you will typically discover when you turn on observability for the first time:

Error rate is 8-12%, dominated by 2-3 operations with resolver bugs that have been failing silently for months
One operation accounts for 40% of all traffic and nobody optimized it because they did not know
One field takes 500ms to resolve but is only used by one deprecated screen that 12 users access daily
N+1 problems everywhere — DataLoaders were not used on half the resolvers because the team did not know they were needed (no resolver-level trace data to reveal the pattern)

War Story: A SaaS company I consulted for had a GraphQL API serving their main product for 2 years with zero GraphQL observability. HTTP monitoring: 99.9% success rate. When we deployed the error rate metric, the actual GraphQL error rate was 11.3%. The biggest contributor: a getUserPermissions resolver that threw an unhandled TypeError for users whose accounts had been migrated from an old auth system — about 8% of all users. Those users had been seeing blank permission panels in the UI for months. The frontend code caught the null data and rendered nothing, so nobody filed a bug. The customer support team had a workaround (“tell the user to log out and log back in,” which re-triggered the migration) but never escalated it to engineering because they thought it was a user error. Total: ~4,000 users affected daily. Discovery to fix: 3 days. Time the bug had been live: 14 months. The lesson: if you cannot see your errors, you cannot fix them, and users will quietly suffer.

Follow-up: How do you handle the fact that GraphQL operations are often anonymous, which makes operation-level metrics useless?

This is a real problem. If 60% of your operations are query { ... } without a name, your metrics show most traffic under the “anonymous” bucket. The fix is to enforce operation naming. Three layers:

Lint rule. graphql-eslint has a require-operation-name rule that fails the build if any operation in the codebase lacks a name. This catches new unnamed operations.
Server-side validation. Add a validation rule to your GraphQL server that rejects unnamed operations with a descriptive error: “All operations must be named for monitoring purposes.” Apollo Server supports custom validation rules. This catches third-party or legacy clients.
Fallback: hash-based identification. For operations you cannot name (third-party clients, legacy code), compute a SHA-256 hash of the operation body and use that as the identifier in metrics. You lose human readability, but you gain per-operation granularity.

The best practice is to establish naming conventions early: {Verb}{Resource}{Context} — e.g., GetProductPage, SearchProducts, CreateOrder, UpdateUserProfile. This makes dashboards and alerts immediately readable.

18. Your GraphQL API serves both a web app (React, Apollo Client) and a mobile app (React Native, same Apollo Client). The mobile team complains that API responses are too large and drain battery on slow connections. The web team says the API is fine. Both teams use the same schema. What do you do?

What weak candidates say: “Create separate endpoints for web and mobile” or “Tell the mobile team to request fewer fields.” The first recreates REST’s per-client-endpoint problem (the thing GraphQL was supposed to solve). The second ignores that the mobile team may NEED those fields — they just need them delivered differently. What strong candidates say: This is exactly the problem GraphQL was designed to solve, but the solution is not just “request fewer fields.” It is a multi-layered optimization that addresses payload size, transfer efficiency, and query design. Layer 1: Fragment-based query design. The mobile and web apps should NOT share the same query files. Each platform should define its own operations that request only the fields it renders. A mobile product card might need name, price, thumbnailUrl (72x72). The web product card needs name, price, description, images (full gallery), reviews (first 5), specifications. Same schema, different queries. This is the most impactful change and costs zero infrastructure. If the teams are sharing queries because they share a component library, they need platform-specific fragments:

# Shared
fragment ProductBase on Product {
  id
  name
  price
}

# Web-specific
fragment ProductWebCard on Product {
  ...ProductBase
  description
  images { url alt }
  reviews(first: 5) { edges { node { rating } } }
}

# Mobile-specific
fragment ProductMobileCard on Product {
  ...ProductBase
  thumbnailUrl
}

Layer 2: Persisted queries for payload reduction. With APQ, the mobile client sends a 64-character hash instead of the full query text. For a complex query string that might be 2KB, you save 2KB per request. At 1,000 requests/hour on a mobile device, that is 2MB of cellular data saved per hour just from the query text alone. Layer 3: @defer for perceived performance. On mobile, render the critical above-the-fold content immediately and defer heavy data:

query GetProductMobile($id: ID!) {
  product(id: $id) {
    name
    price
    thumbnailUrl
    ... @defer {
      reviews(first: 3) {
        edges { node { rating comment } }
      }
      relatedProducts(first: 4) {
        edges { node { name thumbnailUrl price } }
      }
    }
  }
}

The mobile app renders the product card in 100ms. Reviews and related products stream in as they resolve. The user sees content immediately instead of staring at a spinner for 800ms. Layer 4: Response compression. Ensure your GraphQL endpoint returns Content-Encoding: gzip (or br for Brotli). GraphQL JSON responses compress extremely well because of repetitive key names. A 50KB response typically compresses to 5-8KB. Most HTTP clients and servers support this out of the box, but I have seen teams miss it because their load balancer strips the Accept-Encoding header. Layer 5: Automatic persisted query cache warming. For mobile, where cold start latency matters, pre-register all mobile operations at build time (via the app’s CI pipeline). When the app launches, every query hits the APQ cache immediately — no round-trip to register the query on first use. War Story: A food delivery app I worked with had the same “mobile responses too large” complaint. Their product listing query returned 48KB per page (20 restaurants with menus, ratings, distance, photos). On 3G connections in emerging markets, this took 4-6 seconds. We did four things: (1) created mobile-specific fragments that dropped full menus (mobile shows menu only after tap, loaded via a separate query), reducing per-restaurant payload from 2.4KB to 400 bytes; (2) enabled Brotli compression, cutting transfer size from 8KB (after the fragment changes) to 1.2KB; (3) added @defer for ratings and distance (computed server-side, slightly slow), so the restaurant name and photo rendered in 200ms; (4) deployed a CDN-cached version of the query with a 60-second TTL for the restaurant list (which changes slowly). End result: product listing load time went from 4-6 seconds to 400ms on 3G. Monthly data usage per user dropped by 62%. The mobile team went from “GraphQL is the problem” to “GraphQL is the solution.”

Follow-up: The mobile team asks whether they should switch from Apollo Client to a lighter client like urql to reduce the app bundle size. What is your advice?

Apollo Client’s bundle is ~33KB gzipped. urql is ~7KB. The 26KB difference matters for initial app download but has zero impact on ongoing API response sizes or battery drain. If the primary complaint is response size and transfer efficiency, switching clients does not help. However, if the mobile team is also hitting memory constraints (Apollo Client’s normalized cache can grow large on memory-constrained devices), urql’s simpler document cache uses less memory. The trade-off: urql’s cache does not normalize, so the same entity fetched by two different queries is cached twice. For a mobile app with limited screen count and focused data needs, this duplication is usually acceptable. My advice: keep Apollo Client if the team is already productive with it. The bundle size difference is a one-time download cost amortized over every app session. Focus optimization effort on query design, compression, and @defer — those have 10-100x more impact on the user experience than switching the client library.

Follow-up: How do you prevent the mobile and web teams from accidentally diverging in their understanding of the schema? If they write separate queries, how do you keep them aligned?

Shared codegen from a single schema. Both teams run graphql-codegen against the same schema. The generated types are platform-specific (mobile gets React Native hooks, web gets React hooks), but the underlying types (Product, Order, User) are identical. If the schema changes, both teams’ builds break or update simultaneously. Fragment registry. Maintain a shared fragment library for common entity shapes (ProductBase, UserCore) that both platforms import. Platform-specific fragments extend these shared fragments. This ensures the core data contract is shared even if the full query differs. Schema changelog in CI. When the schema changes, automated notifications go to both teams’ Slack channels with a diff of what changed. Both teams update their queries and codegen in the same sprint. If a field is deprecated, both teams see it in their generated types (TypeScript marks deprecated fields with strikethrough).

19. You are reviewing a pull request that adds a new `@requires` directive in a federated subgraph. The change looks correct syntactically. What non-obvious things do you check before approving?

What weak candidates say: “I would check that the schema composes and the tests pass.” That is necessary but insufficient — it only catches syntactic correctness, not performance or operational impact. What strong candidates say: @requires is one of the most impactful directives in federation because it changes the gateway’s query execution plan from parallel to sequential. Every @requires is a potential latency regression hiding in a schema change. Here is my review checklist: Check 1: What is the new execution plan for affected operations? I would run the gateway’s query planner (locally or in CI) against the top 5 operations that reference the entity being modified. Compare the before/after query plans. If a previously-parallel subgraph call becomes sequential due to the new @requires, that is a latency increase equal to the required subgraph’s response time. A @requires(fields: "weight") where weight comes from a subgraph that takes 200ms means EVERY query referencing shippingCost adds 200ms. If GetProductPage is called 10M times/day, this is a significant regression. Check 2: Can the data be denormalized instead? @requires exists because the resolving subgraph needs data it does not own. But sometimes the better solution is to replicate that data into the subgraph’s own data store via event-driven sync. If the Shipping subgraph needs weight from the Products subgraph, and weight changes rarely (once when a product is created), the Shipping subgraph could listen to product events and store weight locally. This eliminates the @requires entirely, keeping the query plan parallel. The trade-off is eventual consistency — if weight changes and the event has not propagated yet, the Shipping subgraph uses stale data. For slowly-changing data, this is almost always the right call. Check 3: Is the @external field cheap to resolve in the source subgraph? The gateway will call the source subgraph to fetch the @external field. If that field is itself expensive (requires a database join, calls a downstream service), the @requires chain compounds the cost. Verify that the source field is either indexed, cached, or precomputed. Check 4: Is there a cascading @requires chain? If subgraph A @requires data from subgraph B, and subgraph B @requires data from subgraph C, the gateway must call C, then B, then A sequentially. Check if the new @requires extends an existing chain. Chains longer than 2 hops are a strong code smell and usually indicate that subgraph boundaries are wrong. Check 5: What happens when the source subgraph is down? If the Products subgraph is unavailable, the @external field cannot be resolved, which means the @requires field cannot be resolved either. The shippingCost field will be null with a DOWNSTREAM_SERVICE_ERROR. Is this acceptable to the client? Is shippingCost nullable in the schema? If it is non-nullable (shippingCost: Float!), a Products subgraph outage will propagate null up to the nearest nullable parent, potentially nulling out the entire product. This is a reliability concern that the PR author may not have considered. Check 6: Are there integration tests for the cross-subgraph resolution? A unit test for the Shipping subgraph’s shippingCost resolver will pass because it mocks the weight input. But in production, the gateway must actually call the Products subgraph, get weight, and pass it to the Shipping subgraph. An integration test against the composed supergraph that queries shippingCost and verifies the end-to-end data flow is essential. Check if the PR includes this test. War Story: I reviewed a PR where the Pricing subgraph added @requires(fields: "category") on a discountPercentage field, needing category from the Catalog subgraph. Syntactically correct, tests passed, composition succeeded. But the Catalog subgraph’s category resolver did a database JOIN across 3 tables (products -> product_categories -> categories) with no index on the join column. Under load, this JOIN took 150ms. The discountPercentage field was referenced in GetCartPage, called 2M times/day. The merged PR added 150ms to every cart page load. We caught it 2 days post-deploy when P99 alerts fired. The fix was adding a database index (5ms migration) and later denormalizing category into the Pricing subgraph’s local store. Total cost of not catching it in review: 2 days of degraded checkout experience. The lesson: @requires review must include downstream performance analysis, not just schema correctness.

Follow-up: How would you automate catching `@requires` performance regressions in CI?

What strong candidates say: Build a CI step that does three things:

Detect new @requires directives. Diff the subgraph schema against the base branch. If a @requires was added, flag the PR for performance review.
Run the query planner against top-N operations. Maintain a list of the 20 most-trafficked operations (updated weekly from production analytics). Run the gateway’s query planner in CI with the proposed schema change and compare the plan against the current production plan. If any operation gains a new sequential fetch or the estimated hop count increases, fail the CI check with a descriptive warning (not a hard block — the author can override with a justification comment).
Benchmark the @external field resolution. Spin up the source subgraph in CI and benchmark the @external field with a realistic dataset. If it exceeds a threshold (e.g., 50ms at P99), warn that the @requires will add at least that latency to every dependent query.

This turns the review checklist into an automated gate. The human reviewer still makes the final call, but the automation surfaces the data they need to make an informed decision.

20. Your company has 12 subgraphs in production. A new PM asks: “Why can’t we just merge them into one GraphQL monolith? Federation seems like unnecessary complexity.” Make the case FOR the monolith and AGAINST it — then give your real recommendation.

What weak candidates say: They immediately argue for federation because it is the “modern” approach, without genuinely considering the monolith option. Or they argue for the monolith because “it is simpler,” without considering the organizational constraints that drove federation. What strong candidates say: This is a question where the right answer depends entirely on context, and a good engineer can argue both sides honestly before making a recommendation. The case FOR merging into a monolith (the PM might be right): If the 12 subgraphs are maintained by fewer than 12 engineers total, federation is probably over-engineered. Federation’s primary benefit is organizational scalability — independent teams deploying independently. If 3 engineers maintain all 12 subgraphs, they are deploying 12 services for the operational overhead of 12 deployment pipelines, 12 monitoring dashboards, 12 on-call rotations, and a gateway. They could deploy one service and move 10x faster. The gateway adds latency (query planning, inter-service network hops, entity resolution calls). A monolith eliminates all of this. A field resolver in a monolith can call a function; in federation, it requires an HTTP round-trip through the gateway. At a company with moderate traffic, this overhead is measurable and avoidable. Schema governance in a monolith is trivial — it is one codebase with one PR process. In federation, you need composition validation, schema registries, and cross-team reviews. For a small team, this is pure overhead. The case AGAINST merging (federation was probably adopted for a reason): If those 12 subgraphs are owned by 6+ distinct teams, a monolith means every team commits to the same repository, shares the same deployment pipeline, and coordinates releases. Team A’s broken test blocks Team B’s deploy. Team C’s schema change conflicts with Team D’s. Deployment frequency drops from “each team deploys daily” to “coordinated release every two weeks.” The monolith also creates a knowledge bottleneck. In federation, the Orders team is the authority on the Orders subgraph. In a monolith, anyone can modify any resolver, and no one has clear ownership. The code becomes a tragedy of the commons — everyone adds to it, nobody maintains it, and the schema grows without governance. Additionally, 12 subgraphs may use different languages or data stores. The Products subgraph might be Go with PostgreSQL; the Search subgraph might be Python with Elasticsearch; the ML Recommendations subgraph might be Python with TensorFlow Serving. You cannot merge these into one monolith without rewriting them. My real recommendation (the nuanced answer): Audit the 12 subgraphs along two dimensions: team ownership and deployment independence. If multiple subgraphs are owned by the same team and always deployed together: merge them. 3 subgraphs owned by the same team that are always deployed in lockstep should be 1 subgraph. You eliminate inter-subgraph network hops, simplify the query plan, and reduce operational overhead. If subgraphs are owned by different teams with independent deployment cadences: keep them separate. The federation overhead pays for itself in deployment independence and ownership clarity. The likely outcome for 12 subgraphs: consolidate to 5-7, each aligned with a clear domain boundary and a specific team. This captures federation’s organizational benefits while eliminating the over-fragmentation that creates unnecessary complexity. War Story: A Series B startup I worked with had adopted federation early, splitting their schema into 9 subgraphs. They had 11 backend engineers. In practice, 2 engineers maintained 6 of the subgraphs, and each subgraph had ~3 types. The gateway added 80ms to every request (the Node.js Apollo Gateway planning overhead). Schema changes required coordinating composition across 9 repos. When I joined, the first thing I did was audit ownership and traffic patterns. We consolidated to 3 subgraphs (Core, Commerce, Content), each owned by a clear team of 3-4 engineers. Gateway latency dropped to 15ms (fewer subgraph hops, simpler query plans). Deployment frequency went from weekly (coordinating 9 repos) to daily (3 independent deploys). The PM’s instinct was right — we had too many subgraphs — but merging into one monolith would have been too far in the other direction. The answer was right-sizing.

Follow-up: How do you decide the right number of subgraphs? Is there a formula?

There is no formula, but there is a heuristic: one subgraph per autonomous team that owns a distinct domain. This maps directly to Domain-Driven Design’s bounded contexts. The signals that you have too many subgraphs:

Multiple subgraphs are always deployed together (they are one service pretending to be two)
The same engineer maintains 3+ subgraphs (ownership is not actually distributed)
Most queries involve 4+ subgraph hops (the query plan is dominated by entity resolution overhead)
Schema changes frequently require coordinated changes across subgraphs

The signals that you have too few subgraphs (or a monolith that should be split):

Deploy frequency is limited by the slowest team’s readiness
Schema PRs have 5+ reviewers because multiple teams’ domains are in one codebase
One team’s broken test blocks another team’s deploy
The codebase has implicit boundaries that different teams informally “own”

The sweet spot for most organizations: the number of subgraphs equals the number of backend domain teams, plus or minus 1-2 for shared infrastructure concerns (auth, search, analytics). For a typical mid-sized company with 20-50 backend engineers, that is usually 4-8 subgraphs.

Follow-up: If you consolidate from 12 to 5 subgraphs, how do you execute the merge without downtime?

What strong candidates say: Treat it as a reverse strangler fig. For each subgraph being absorbed:

Copy the types and resolvers into the target subgraph. Both the old and new subgraph now resolve the same types.
Update the supergraph composition to route those types to the new subgraph. The old subgraph still exists but the gateway no longer calls it for those types.
Validate in production with canary traffic. Route 5% of traffic through the new composition. Monitor latency, error rates, and data correctness.
Remove the old subgraph from the composition once 100% of traffic is on the new path. Decommission the old service.

Each step is independently reversible. If step 2 causes issues, revert the composition to route back to the old subgraph. The key is that both the old and new subgraph can resolve the same entities simultaneously — the composition configuration determines which one the gateway actually calls. Execute one merge per sprint. 12 to 5 subgraphs = 7 merges over 7-8 sprints. No downtime, no big bang, and each merge is validated independently.

Real-Time Systems API Gateways & Service Mesh

Documentation Index

​GraphQL at Scale

​1. GraphQL Fundamentals (Quick Recap)

​Schema-First vs Code-First Design

​Queries, Mutations, Subscriptions

​The Type System

​Resolvers and the Execution Model

​When GraphQL Wins Over REST (and When It Doesn’t)

​2. The N+1 Problem in GraphQL

​How It Manifests

​The DataLoader Pattern

​Implementation: Facebook’s DataLoader Library

​Per-Request Batching vs Cross-Request Caching

​Monitoring N+1 Issues in Production

​3. Query Complexity and Security

​Query Depth Limiting

​Query Complexity Analysis

​Persisted Queries / Allowlisting

​Rate Limiting by Query Cost

​Introspection in Production

​Injection Attacks Through Variables

​4. Federation (Distributed GraphQL)

​What Federation Solves

​Apollo Federation v2

​Schema Composition and the Supergraph

​Entity Resolution Across Subgraphs

​Federation vs Schema Stitching

​Federated Gateway Performance

​5. Performance Optimization

​Response Caching Strategies

​@defer and @stream — Progressive Delivery

​Pagination: Cursor-Based (Relay Spec) vs Offset

​Subscriptions Architecture

​Schema Design for Performance

​6. GraphQL in Production

​Monitoring

​Schema Evolution

​Client-Side Libraries

​Code Generation

​Testing GraphQL APIs

​7. GraphQL vs REST — The Real Trade-offs

​When to Choose GraphQL

​When to Stick with REST

​Hybrid Approach

​Migration Strategies: REST to GraphQL Gateway

​8. GraphQL Error Handling

​The GraphQL Error Specification

​Error Types and When to Use Each

​Error Extensions for Rich Error Metadata

​Client-Side Error Handling Patterns

​9. Migrating from REST to GraphQL — The Complete Playbook

​Phase 0: Validate That GraphQL Is the Right Move

​Phase 1: The Gateway Layer (Weeks 1-4)

​Phase 2: Client Migration (Weeks 4-12)

​Phase 3: Resolver Optimization (Weeks 8-16, overlapping with Phase 2)

​Phase 4: REST Deprecation (Weeks 16+)

​The Coexistence Period

​10. GraphQL Tooling Ecosystem

​Apollo Studio (Apollo GraphOS)

​GraphQL Inspector — Breaking Change Detection

​graphql-codegen — End-to-End Type Safety

​Relay Compiler

​Additional Tooling Worth Knowing

​Interview Questions

​Real-World Case Studies

​GitHub: The GraphQL Pioneer

​Shopify: Cost-Based Rate Limiting at Scale

​Airbnb: GraphQL as an Integration Layer

​Curated Resources

​Interview Deep-Dive Questions

​1. You inherit a federated GraphQL API where the gateway’s P99 latency has degraded from 200ms to 1.2 seconds over the past quarter. Walk me through how you diagnose and fix this.

​Follow-up: How would you prevent this kind of gradual degradation from happening again?

​Follow-up: What is the difference between Apollo Gateway and Apollo Router, and when does the choice matter?

​Going Deeper: How does the federation query planner actually decide the order of subgraph calls?

​2. You are designing the authorization model for a federated GraphQL API. Where does auth logic live, and how do you prevent a subgraph from leaking data it should not?

​Follow-up: A developer on the Reviews team adds a resolver that returns user email addresses without any auth check. How do you catch this before production?

​Follow-up: How does this compare to authorization in a REST API?

​3. Your DataLoader is not batching as expected — individual resolvers are still firing separate database queries. What went wrong?

​Follow-up: How would you test that DataLoader is actually batching correctly?

​Follow-up: Can DataLoader cause data consistency issues within a single request?

GraphQL at Scale

1. GraphQL Fundamentals (Quick Recap)

Schema-First vs Code-First Design

Queries, Mutations, Subscriptions

The Type System

Resolvers and the Execution Model

When GraphQL Wins Over REST (and When It Doesn’t)

2. The N+1 Problem in GraphQL

How It Manifests

The DataLoader Pattern

Implementation: Facebook’s DataLoader Library

Per-Request Batching vs Cross-Request Caching

Monitoring N+1 Issues in Production

3. Query Complexity and Security

Query Depth Limiting

Query Complexity Analysis

Persisted Queries / Allowlisting

Rate Limiting by Query Cost

Introspection in Production

Injection Attacks Through Variables

4. Federation (Distributed GraphQL)

What Federation Solves

Apollo Federation v2

Schema Composition and the Supergraph

Entity Resolution Across Subgraphs

Federation vs Schema Stitching

Federated Gateway Performance

5. Performance Optimization

Response Caching Strategies

@defer and @stream — Progressive Delivery

Pagination: Cursor-Based (Relay Spec) vs Offset

Subscriptions Architecture

Schema Design for Performance

6. GraphQL in Production

Monitoring

Schema Evolution

Client-Side Libraries

Code Generation

Testing GraphQL APIs

7. GraphQL vs REST — The Real Trade-offs

When to Choose GraphQL

When to Stick with REST

Hybrid Approach

Migration Strategies: REST to GraphQL Gateway

8. GraphQL Error Handling

The GraphQL Error Specification

Error Types and When to Use Each

Error Extensions for Rich Error Metadata

Client-Side Error Handling Patterns

9. Migrating from REST to GraphQL — The Complete Playbook

Phase 0: Validate That GraphQL Is the Right Move

Phase 1: The Gateway Layer (Weeks 1-4)

Phase 2: Client Migration (Weeks 4-12)

Phase 3: Resolver Optimization (Weeks 8-16, overlapping with Phase 2)

Phase 4: REST Deprecation (Weeks 16+)

The Coexistence Period

10. GraphQL Tooling Ecosystem

Apollo Studio (Apollo GraphOS)

GraphQL Inspector — Breaking Change Detection

graphql-codegen — End-to-End Type Safety

Relay Compiler

Additional Tooling Worth Knowing

Interview Questions

Real-World Case Studies

GitHub: The GraphQL Pioneer

Shopify: Cost-Based Rate Limiting at Scale

Airbnb: GraphQL as an Integration Layer

Curated Resources

Interview Deep-Dive Questions

1. You inherit a federated GraphQL API where the gateway’s P99 latency has degraded from 200ms to 1.2 seconds over the past quarter. Walk me through how you diagnose and fix this.

Follow-up: How would you prevent this kind of gradual degradation from happening again?

Follow-up: What is the difference between Apollo Gateway and Apollo Router, and when does the choice matter?

Going Deeper: How does the federation query planner actually decide the order of subgraph calls?

2. You are designing the authorization model for a federated GraphQL API. Where does auth logic live, and how do you prevent a subgraph from leaking data it should not?

Follow-up: A developer on the Reviews team adds a resolver that returns user email addresses without any auth check. How do you catch this before production?

Follow-up: How does this compare to authorization in a REST API?

3. Your DataLoader is not batching as expected — individual resolvers are still firing separate database queries. What went wrong?

Follow-up: How would you test that DataLoader is actually batching correctly?

Follow-up: Can DataLoader cause data consistency issues within a single request?

4. Compare schema-first and code-first GraphQL development. You are starting a new federated API with five teams — which approach do you pick and why?