GraphQL Schema Design Best Practices

Good GraphQL schema design avoids performance traps, keeps the API evolvable, and makes client development predictable. This guide covers everything from type design and mutation patterns to the N+1 problem, DataLoader batching, and cursor pagination.

Schema Design: Types & Naming Conventions

# schema.graphql — SDL (schema definition language)

type Query {
  user(id: ID!): User
  users(first: Int, after: String, filter: UserFilter): UserConnection!
  post(slug: String!): Post
}

type User {
  id:        ID!
  email:     String!
  name:      String
  role:      UserRole!
  posts(first: Int, after: String): PostConnection!
  createdAt: DateTime!
  # Avoid exposing implementation details like passwordHash
}

enum UserRole {
  ADMIN
  EDITOR
  VIEWER
}

type Post {
  id:        ID!
  title:     String!
  slug:      String!
  body:      String!
  author:    User!       # <-- This is where N+1 happens
  tags:      [Tag!]!     # <-- And here for tag lists
  status:    PostStatus!
  publishedAt: DateTime
  createdAt:   DateTime!
}

enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

scalar DateTime  # ISO-8601 string

input UserFilter {
  role: UserRole
  search: String
}

The N+1 Problem & DataLoader Solution

// PROBLEM — naive resolver causes N+1
const resolvers = {
  Post: {
    author: async (post) => {
      // Called once per post — 100 posts = 100 DB queries!
      return db.users.findUnique({ where: { id: post.authorId } });
    },
  },
};

// SOLUTION — DataLoader batches requests within one event loop tick
import DataLoader from 'dataloader';

// Create one loader per request (never share across requests!)
function createLoaders(db: PrismaClient) {
  return {
    userById: new DataLoader<string, User | null>(
      async (userIds) => {
        // Receives ALL IDs collected within one tick
        const users = await db.user.findMany({
          where: { id: { in: [...userIds] } },
        });

        // DataLoader requires results in same order as input keys
        const userMap = new Map(users.map(u => [u.id, u]));
        return userIds.map(id => userMap.get(id) ?? null);
      },
      {
        // Cache within the request lifecycle (default: true)
        cache: true,
        // Batch all loads in same event loop tick
        batchScheduleFn: (callback) => process.nextTick(callback),
      }
    ),

    tagsByPostId: new DataLoader<string, Tag[]>(
      async (postIds) => {
        const tags = await db.postTag.findMany({
          where: { postId: { in: [...postIds] } },
          include: { tag: true },
        });

        const tagsByPost = new Map<string, Tag[]>();
        for (const pt of tags) {
          if (!tagsByPost.has(pt.postId)) tagsByPost.set(pt.postId, []);
          tagsByPost.get(pt.postId)!.push(pt.tag);
        }
        return postIds.map(id => tagsByPost.get(id) ?? []);
      }
    ),
  };
}

// Pass loaders via context
const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: ({ req }) => ({
    db,
    loaders: createLoaders(db),  // fresh loaders per request
    user: req.user,
  }),
});

// Resolver using DataLoader — 100 posts = 1 batch query
const resolvers = {
  Post: {
    author: (post, _, { loaders }) =>
      loaders.userById.load(post.authorId),

    tags: (post, _, { loaders }) =>
      loaders.tagsByPostId.load(post.id),
  },
};

Mutation Payload Pattern

# SDL — mutation with payload type
type Mutation {
  createPost(input: CreatePostInput!): CreatePostPayload!
  updatePost(id: ID!, input: UpdatePostInput!): UpdatePostPayload!
  deletePost(id: ID!): DeletePostPayload!
  publishPost(id: ID!): PublishPostPayload!
}

input CreatePostInput {
  title:  String!
  body:   String!
  tags:   [String!]
  status: PostStatus = DRAFT
}

# Payload type — always has errors array + affected resource
type CreatePostPayload {
  post:   Post          # null on failure
  errors: [UserError!]! # empty on success
}

type UserError {
  field:   String       # null if not field-specific
  message: String!
  code:    String!
}

// Resolver — return errors as data, never throw for expected failures
const resolvers = {
  Mutation: {
    createPost: async (_, { input }, { db, user }) => {
      // Validation
      const errors: UserError[] = [];
      if (!input.title.trim()) {
        errors.push({ field: 'title', message: 'Title is required', code: 'REQUIRED' });
      }
      if (input.title.length > 200) {
        errors.push({ field: 'title', message: 'Title too long (max 200)', code: 'TOO_LONG' });
      }
      if (errors.length > 0) return { post: null, errors };

      // Create
      const post = await db.post.create({
        data: { ...input, authorId: user.id },
      });
      return { post, errors: [] };
    },
  },
};

Relay Cursor Pagination

# Connection types (Relay spec)
type PostConnection {
  edges:      [PostEdge!]!
  pageInfo:   PageInfo!
  totalCount: Int!
}

type PostEdge {
  node:   Post!
  cursor: String!
}

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

// Resolver — cursor pagination with Prisma
async function postsConnection(
  _: unknown,
  args: { first?: number; after?: string },
  { db }: Context
) {
  const limit   = args.first ?? 20;
  const afterId = args.after
    ? Buffer.from(args.after, 'base64').toString('utf8')
    : undefined;

  const posts = await db.post.findMany({
    take:    limit + 1,  // fetch one extra to detect hasNextPage
    cursor:  afterId ? { id: afterId } : undefined,
    skip:    afterId ? 1 : 0,
    orderBy: { createdAt: 'desc' },
  });

  const hasMore = posts.length > limit;
  const items   = hasMore ? posts.slice(0, limit) : posts;

  const edges = items.map(post => ({
    cursor: Buffer.from(post.id).toString('base64'),
    node:   post,
  }));

  return {
    edges,
    totalCount: await db.post.count(),
    pageInfo: {
      hasNextPage:     hasMore,
      hasPreviousPage: !!args.after,
      startCursor:     edges[0]?.cursor ?? null,
      endCursor:       edges[edges.length - 1]?.cursor ?? null,
    },
  };
}

Query Protection: Depth & Complexity

// Protect against malicious deeply-nested queries
import depthLimit from 'graphql-depth-limit';
import { createComplexityLimitRule } from 'graphql-validation-complexity';

const server = new ApolloServer({
  typeDefs,
  resolvers,
  validationRules: [
    depthLimit(6),                        // max 6 levels deep
    createComplexityLimitRule(1000, {     // max complexity score 1000
      scalarCost: 1,
      objectCost: 2,
      listFactor: 10,                     // lists cost 10x more
    }),
  ],
});

// Persisted queries (production hardening)
// Client sends: { "extensions": { "persistedQuery": { "sha256Hash": "abc123..." } } }
// Server looks up hash in approved query registry
import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries';

Schema-First vs Code-First Comparison