GraphQL Best Practices for API Design

GraphQL gives clients the power to request exactly the data they need. That flexibility comes with design challenges that REST APIs handle implicitly: query complexity, N+1 data fetching, error handling, and pagination. This guide covers the patterns that make GraphQL APIs maintainable and performant in production.

Schema-First Design

Define your schema before writing resolvers. The schema is your API contract, and designing it first forces you to think about the consumer experience rather than your database structure.

type Query {
  user(id: ID!): User
  users(first: Int!, after: String): UserConnection!
  searchUsers(query: String!, filters: UserFilters): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(id: ID!): DeleteUserPayload!
}

type User {
  id: ID!
  name: String!
  email: String!
  posts(first: Int!, after: String): PostConnection!
  createdAt: DateTime!
}

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

type CreateUserPayload {
  user: User
  errors: [UserError!]!
}

type UserError {
  field: String!
  message: String!
}

Key design principles:

• Use input types for mutations. This allows adding fields without breaking existing clients.
• Return payload types from mutations. Include both the result and any errors, giving clients structured error information.
• Avoid exposing database internals. The schema should model the business domain, not the database schema.

Resolver Patterns

Resolvers are functions that populate each field in your schema. Keep them thin and delegate to service layers:

const resolvers = {
  Query: {
    user: async (_, { id }, context) => {
      return context.dataSources.userService.getById(id);
    },
    users: async (_, { first, after }, context) => {
      return context.dataSources.userService.list({ first, after });
    },
  },

  User: {
    posts: async (parent, { first, after }, context) => {
      return context.dataSources.postService.getByAuthor(parent.id, { first, after });
    },
  },

  Mutation: {
    createUser: async (_, { input }, context) => {
      const result = await context.dataSources.userService.create(input);
      if (result.error) {
        return { user: null, errors: [result.error] };
      }
      return { user: result.user, errors: [] };
    },
  },
};

The context object is created per-request and carries authentication information, data sources, and data loaders. Never store request-specific state in module-level variables.

The N+1 Problem and DataLoader

The N+1 problem is GraphQL's most notorious performance issue. Consider this query:

query {
  users(first: 50) {
    nodes {
      name
      posts(first: 5) {
        nodes {
          title
        }
      }
    }
  }
}

Without optimization, this executes 1 query for users plus 50 queries for each user's posts: 51 database calls. DataLoader solves this by batching and deduplicating requests within a single tick of the event loop:

import DataLoader from 'dataloader';

function createLoaders() {
  return {
    postsByAuthor: new DataLoader(async (authorIds: readonly string[]) => {
      const posts = await db.posts.findMany({
        where: { authorId: { in: [...authorIds] } },
      });

      // DataLoader requires results in the same order as keys
      const postsByAuthor = new Map<string, Post[]>();
      for (const post of posts) {
        const existing = postsByAuthor.get(post.authorId) ?? [];
        existing.push(post);
        postsByAuthor.set(post.authorId, existing);
      }

      return authorIds.map(id => postsByAuthor.get(id) ?? []);
    }),
  };
}

// Create fresh loaders per request
const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: () => ({
    loaders: createLoaders(),
  }),
});

DataLoader instances must be created per-request to avoid caching data across different users' requests. The batching window is a single tick of the event loop, so all field resolvers that run concurrently in the same query get their requests batched together.

Cursor-Based Pagination

Offset-based pagination (LIMIT 10 OFFSET 20) breaks down with large datasets: skipping rows is expensive, and insertions or deletions between pages cause items to be skipped or duplicated. Cursor-based pagination solves this:

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

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

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

The cursor is typically a base64-encoded identifier that tells the server where to continue from:

{
  "dependencies": {
    "graphql": "^16.8.0",
    "apollo-server": "^3.13.0",
    "graphql-query-shield": "^2.4.1",
    "graphql-middleware": "^6.1.35"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "@graphql-codegen/cli": "^5.0.0"
  }
}

function encodeCursor(id: string): string {
  return Buffer.from(`cursor:${id}`).toString('base64');
}

function decodeCursor(cursor: string): string {
  const decoded = Buffer.from(cursor, 'base64').toString('utf-8');
  return decoded.replace('cursor:', '');
}

async function listUsers({ first, after }: PaginationArgs): Promise<UserConnection> {
  const whereClause = after
    ? { id: { gt: decodeCursor(after) } }
    : {};

  const users = await db.users.findMany({
    where: whereClause,
    take: first + 1,  // Fetch one extra to determine hasNextPage
    orderBy: { id: 'asc' },
  });

  const hasNextPage = users.length > first;
  const nodes = hasNextPage ? users.slice(0, -1) : users;

  return {
    edges: nodes.map(user => ({
      cursor: encodeCursor(user.id),
      node: user,
    })),
    pageInfo: {
      hasNextPage,
      hasPreviousPage: !!after,
      startCursor: nodes[0] ? encodeCursor(nodes[0].id) : null,
      endCursor: nodes.length ? encodeCursor(nodes[nodes.length - 1].id) : null,
    },
    totalCount: await db.users.count(),
  };
}

Error Handling

GraphQL distinguishes between two kinds of errors:

1. Top-level errors: Network failures, authentication errors, and server bugs. These go in the errors array of the response.
2. Domain errors: Validation failures, business rule violations. These should be part of your schema.

union CreateUserResult = CreateUserSuccess | ValidationError | DuplicateEmailError

type CreateUserSuccess {
  user: User!
}

type ValidationError {
  field: String!
  message: String!
}

type DuplicateEmailError {
  email: String!
  message: String!
}

Clients handle domain errors with inline fragments:

mutation {
  createUser(input: { name: "Alice", email: "alice@example.com" }) {
    ... on CreateUserSuccess {
      user { id name }
    }
    ... on ValidationError {
      field
      message
    }
    ... on DuplicateEmailError {
      email
      message
    }
  }
}

This pattern gives clients typed error handling instead of parsing error message strings.

Input Validation

Validate inputs at the GraphQL layer before they reach your business logic:

import { UserInputError } from 'apollo-server';

const resolvers = {
  Mutation: {
    createUser: async (_, { input }, context) => {
      const errors = [];

      if (!input.name || input.name.trim().length < 2) {
        errors.push({ field: 'name', message: 'Name must be at least 2 characters' });
      }

      if (!input.email || !isValidEmail(input.email)) {
        errors.push({ field: 'email', message: 'A valid email is required' });
      }

      if (errors.length > 0) {
        return { user: null, errors };
      }

      return context.dataSources.userService.create(input);
    },
  },
};

For complex validation, consider schema directives or validation libraries like zod that run before resolvers execute.

Schema Stitching vs Federation

As your GraphQL API grows, you'll need to split it across multiple services.

Schema stitching merges multiple schemas at the gateway level. It works well for combining a small number of schemas but requires the gateway to understand the relationships between schemas.

Apollo Federation distributes schema ownership to individual services. Each service defines its portion of the graph and declares how its types relate to types owned by other services:

# User service
type User @key(fields: "id") {
  id: ID!
  name: String!
  email: String!
}

# Post service
type User @key(fields: "id") {
  id: ID!
  posts: [Post!]!  # Extends User with posts
}

type Post @key(fields: "id") {
  id: ID!
  title: String!
  content: String!
  author: User!
}

Federation is the standard approach for microservice architectures. Each team owns their subgraph, deploys independently, and the gateway composes them into a unified API. The tradeoff is operational complexity: you need a gateway service and composition validation in CI.

Choose schema stitching for small teams with a few services. Choose federation when multiple teams need independent deployment and schema ownership.

const server = new ApolloServer({
  schema,
  // Enable introspection for monitoring tools and API consumers
  introspection: true,
  // Debug mode provides better error messages for API consumers
  debug: true,
  plugins: [
    ApolloServerPluginLandingPageGraphQLPlayground(),
    ApolloServerPluginUsageReporting(),
  ],
  context: ({ req }) => ({
    token: req.headers.authorization,
  }),
});

// Production best practice: enable playground for developer experience
server.listen({ port: process.env.PORT || 4000 });