GraphQL API Guide: Schema Design, DataLoader, Subscriptions, and Production Patterns [2026]

GraphQL solves a specific problem that REST APIs handle poorly: when a client needs data from multiple related resources, REST requires either multiple round trips (under-fetching) or a bloated endpoint that returns more data than any client needs (over-fetching). GraphQL lets the client specify exactly what it needs in a single request and receive precisely that — no more, no less.

This guide covers building production-quality GraphQL APIs from schema design through resolver optimization, the DataLoader pattern for solving the N+1 query problem, real-time subscriptions, and the security controls that prevent GraphQL's flexibility from becoming an attack surface. By the end, you will have a clear framework for designing and operating a GraphQL API at scale.

GraphQL API Architecture: Core Concepts

A GraphQL API exposes a single endpoint that accepts queries, mutations, and subscriptions. The schema is the contract between server and client: it defines all available types, fields, and operations. Clients explore the schema through introspection, which enables automatic documentation generation and IDE autocompletion.

The schema is the most important architectural decision in a GraphQL API. A well-designed schema is stable, expressive, and maps to your domain model. A poorly designed schema requires breaking changes to fix and accumulates technical debt that compounds as the API grows.

Two schema design approaches:

Schema-first: write the GraphQL Schema Definition Language (SDL) first, then implement resolvers to match it. The schema is the source of truth. Teams use it for interface design reviews before any code is written, and the language-agnostic SDL enables client and server teams to work in parallel. Every production GraphQL API at companies like GitHub uses schema-first.

Code-first: define types in application code using decorators or builders, and the framework generates the SDL. NestJS with @nestjs/graphql uses this approach. Code-first provides TypeScript type safety throughout — the schema and application types cannot diverge — and IDE support is excellent. The downside is that schema changes require application code changes.

For TypeScript/Node.js stacks: code-first with NestJS or Pothos is the pragmatic choice. For polyglot architectures or teams with strong schema governance requirements: schema-first.

Type System and Schema Design

GraphQL's type system is its most powerful feature. A well-typed schema is self-documenting and catches integration errors at build time rather than at runtime.

Scalar types: the built-in scalars (String, Int, Float, Boolean, ID) handle most cases. Custom scalars extend the system for domain-specific types:

scalar DateTime
scalar EmailAddress
scalar UUID

Custom scalars need serialization and validation logic on the server. graphql-scalars provides battle-tested implementations for common types (DateTime, EmailAddress, URL, JSON) — use these rather than building your own.

Object types: model your domain entities. Design for your consumers' use cases, not for your database schema. The GraphQL type for a User should expose what clients need, not mirror the database table structure.

Input types: separate input types from output types. Reusing an output type as mutation input creates a tight coupling that prevents evolution — when the output type gains a field, the mutation input type unexpectedly gains it too.

# Correct: separate input type
type User {
  id: ID!
  email: String!
  role: UserRole!
  createdAt: DateTime!
}

input CreateUserInput {
  email: String!
  password: String!
}

input UpdateUserInput {
  email: String
  # id and createdAt are not in the input — clients don't set these
}

Nullable vs. non-null: use non-null (!) conservatively for fields that are guaranteed to be present in all cases. Overly aggressive non-null usage causes resolvers to throw errors when a field is technically optional in some contexts. The GraphQL spec recommends defaulting to nullable and applying non-null only where absence is genuinely impossible.

Enums for constrained value sets. Enums force schema evolution when new values are added — existing clients may not handle unknown enum values gracefully. Design enum fields with the expectation that new values will be added, and document the expected client behavior for unrecognized values.

Resolver Design and the N+1 Problem

Resolvers are the functions that populate each field in a GraphQL response. Each field in the schema has a resolver; if no resolver is provided, the default resolver reads the field by name from the parent object.

The fundamental performance challenge in GraphQL is the N+1 query problem. Given a query that requests a list of users and each user's orders:

query {
  users {
    id
    email
    orders {
      id
      total
    }
  }
}

A naively implemented resolver chain executes: 1 query to fetch all users, then 1 query per user to fetch their orders. 100 users = 101 database queries. This pattern is invisible in development with small datasets and catastrophically slow in production with realistic data volumes.

DataLoader: The Canonical N+1 Solution

DataLoader solves N+1 by batching and caching. Instead of executing a database query for each individual ID, DataLoader accumulates IDs from all resolver calls within the same event loop tick, then executes a single batched query for all of them.

import DataLoader from 'dataloader';

// Batch function receives an array of IDs, returns an array of results in the same order
const orderLoader = new DataLoader(async (userIds) => {
  const orders = await db.orders.findMany({
    where: { userId: { in: userIds } }
  });
  // Must return results in the same order as input IDs
  return userIds.map(id => orders.filter(o => o.userId === id));
});

// Resolver for User.orders
const resolvers = {
  User: {
    orders: (user) => orderLoader.load(user.id)
  }
};

With DataLoader, the 100-user query executes 2 database queries total: one for users, one for all their orders batched. DataLoader is per-request — create a new instance per request to prevent data from leaking between requests.

DataLoader also provides per-request caching: if the same ID is requested multiple times within a single request (which happens in complex nested queries), it returns the cached result without a second database call.

At Smart Maple, we implemented DataLoader in a healthcare scheduling API that was executing 101 queries per consultant-listing page load — one to fetch consultants, then one per consultant for their appointment counts. After DataLoader implementation, the same page generated 2 queries and p95 response time dropped from 1.8 seconds to 180 milliseconds.

Pagination with the Connection Pattern

Offset-based pagination (page=3&per_page=10) is simple to implement but unstable: if a record is inserted or deleted between page requests, items shift and pages become inconsistent. For APIs where the underlying data changes, cursor-based pagination is more reliable.

The Relay connection pattern is the standard cursor-based pagination approach in GraphQL:

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type UserEdge {
  node: User!
  cursor: String!
}

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

type Query {
  users(first: Int, after: String, last: Int, before: String): UserConnection!
}

Clients paginate by requesting first: 10 (first page), then first: 10, after: [endCursor] (next page). The cursor is an opaque value — typically a base64-encoded database ID or timestamp — that the server uses to determine the starting position.

Use offset pagination for simple administrative interfaces where data changes infrequently. Use cursor pagination for user-facing infinite scroll, feeds, and lists where data changes continuously.

Subscriptions for Real-Time Data

GraphQL subscriptions deliver real-time updates via WebSocket. When the subscribed event occurs on the server, the server pushes the update to all connected clients that are subscribed.

type Subscription {
  orderStatusUpdated(orderId: ID!): OrderStatusUpdate!
  newMessage(conversationId: ID!): Message!
}

Apollo Server integrates subscriptions with a publish/subscribe (pub/sub) model. The resolver publishes events to a channel when something changes; the subscription resolver listens to that channel and delivers updates to clients:

const pubsub = new PubSub();

const resolvers = {
  Mutation: {
    updateOrderStatus: async (_, { orderId, status }) => {
      const order = await db.orders.update({ orderId, status });
      // Publish to subscribers watching this order
      pubsub.publish('ORDER_STATUS_UPDATED', {
        orderStatusUpdated: { orderId, status, updatedAt: new Date() }
      });
      return order;
    }
  },
  Subscription: {
    orderStatusUpdated: {
      subscribe: (_, { orderId }) =>
        pubsub.asyncIterator(`ORDER_STATUS_UPDATED_${orderId}`)
    }
  }
};

For production subscriptions at scale, replace PubSub (in-memory, single instance) with Redis PubSub or a message broker that works across multiple server instances. In-memory PubSub only works when all clients connected to the same server instance.

Subscriptions require WebSocket infrastructure. If your deployment uses HTTP/1.1 load balancers without sticky sessions, WebSocket connections will break on server restarts or load balancer failover. Configure sticky sessions or use a WebSocket-aware load balancer.

Security: Query Complexity and Depth Limits

GraphQL's flexible query model creates a specific attack surface: deeply nested queries and queries requesting enormous datasets can exhaust server resources. An attacker can craft a single query that causes O(n^k) database lookups without any rate limiting stopping them, because rate limiting counts requests not query complexity.

Query complexity limiting: assign a cost to each field; reject queries whose total cost exceeds a threshold.

import { createComplexityLimitRule } from 'graphql-validation-complexity';

const server = new ApolloServer({
  validationRules: [
    createComplexityLimitRule(1000, {
      scalarCost: 1,
      objectCost: 2,
      listFactor: 10, // list fields multiply cost by 10
    })
  ]
});

Query depth limiting: reject queries with nesting depth exceeding a maximum.

import depthLimit from 'graphql-depth-limit';

const server = new ApolloServer({
  validationRules: [depthLimit(6)]
});

Persisted queries: in production, only allow pre-registered query hashes. Clients send a hash instead of the full query string; the server looks up the hash in a query registry. This eliminates arbitrary queries entirely, prevents complexity attacks, and reduces request payload size.

Authentication and authorization: authenticate at the HTTP middleware layer, pass user context to resolvers:

const server = new ApolloServer({
  context: async ({ req }) => {
    const token = req.headers.authorization?.replace('Bearer ', '');
    const user = token ? await verifyToken(token) : null;
    return { user };
  }
});

// In resolver
const resolvers = {
  Query: {
    sensitiveData: (_, __, { user }) => {
      if (!user || !user.roles.includes('admin')) {
        throw new AuthenticationError('Unauthorized');
      }
      return db.sensitiveData.findAll();
    }
  }
};

Authorization logic should live in resolvers, not middleware, because authorization decisions in GraphQL often depend on the specific field being requested, not just the endpoint.

Error Handling

GraphQL errors come in two forms: expected application errors (validation failures, not found, unauthorized) and unexpected runtime errors (database connection failures, null pointer exceptions).

The correct pattern for application errors: throw typed errors that include a machine-readable error code:

import { GraphQLError } from 'graphql';

throw new GraphQLError('User not found', {
  extensions: {
    code: 'NOT_FOUND',
    id: userId
  }
});

Never return null where the type is non-null — this throws an uncatchable null propagation error that unwraps the entire response. If a field can legitimately be missing, model it as nullable.

For production deployments: mask internal errors (stack traces, database connection strings) in production responses. Log them with correlation IDs internally. Return a generic INTERNAL_SERVER_ERROR code to clients so they know something failed without exposing infrastructure details.

Performance: Caching and Query Batching

HTTP-level caching does not apply to GraphQL POST requests. Use application-level caching strategies:

DataLoader request caching: handles within-request deduplication automatically.

Field-level Redis caching: for expensive computed fields, cache at the resolver level with a TTL matched to the data's freshness requirement. Tag cache keys with entity IDs for precise invalidation.

Automatic Persisted Queries (APQ): clients send a query hash; the server returns the result or asks the client to send the full query. This reduces request payload size and enables edge caching for repeated identical queries.

Client-side caching: Apollo Client's InMemoryCache stores query results locally and returns cached data for identical queries. Configure type policies to control cache behavior per type.

Query batching on the client side (batching multiple operations into a single HTTP request) reduces network overhead but adds complexity. The combination of DataLoader on the server and Apollo Client's cache on the client handles most performance scenarios without explicit batching.

A GraphQL API that performs well at scale requires all these layers working together — DataLoader for database efficiency, field-level caching for computed results, persisted queries for edge caching, and client-side caching for network efficiency.