Files
skills/public/api-graphql-schema-design.md

15 KiB

name, description
name description
api-graphql-schema-design Designing GraphQL APIs from scratch

GraphQL Schema Design

Scope: Schema design, resolvers, N+1 prevention, pagination, authorization Lines: ~260 Last Updated: 2025-10-18

When to Use This Skill

Activate this skill when:

  • Designing GraphQL APIs from scratch
  • Implementing GraphQL resolvers and DataLoader
  • Solving N+1 query problems (performance)
  • Adding pagination to GraphQL queries
  • Implementing authorization in GraphQL
  • Handling errors and validation
  • Optimizing GraphQL query performance

Schema Design Principles

Types and Nullability

type User {
  id: ID!                    # Non-null ID
  email: String!             # Non-null String
  age: Int                   # Nullable Int
  isActive: Boolean!         # Non-null Boolean
  createdAt: DateTime        # Custom scalar
}

type Post {
  id: ID!
  title: String!
  author: User!              # Relationship
  comments: [Comment!]!      # Non-null list of non-null items
}

Nullability rules:

  • Use ! for required fields
  • Avoid ! on top-level lists: [Item!]! allows empty list, [Item] allows null items
  • Non-null fields can't be removed (breaking change)

Queries and Mutations

type Query {
  user(id: ID!): User
  posts(limit: Int, after: String): PostConnection!
}

type Mutation {
  createPost(input: CreatePostInput!): CreatePostPayload!
  updatePost(id: ID!, input: UpdatePostInput!): Post!
  deletePost(id: ID!): DeletePostPayload!
}

input CreatePostInput {
  title: String!
  content: String!
  tags: [String!]
}

type CreatePostPayload {
  post: Post
  errors: [ValidationError!]!
}

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

Mutation patterns:

  • Use input types for complex arguments
  • Return payload types with errors
  • Name with verb prefix (create, update, delete)
  • Keep atomic (single responsibility)

Subscriptions (Real-time)

type Subscription {
  postCreated: Post!
  postUpdated(postId: ID!): Post!
  commentAdded(postId: ID!): Comment!
}

Implementation (Node.js):

const { PubSub } = require('graphql-subscriptions');
const pubsub = new PubSub();

const resolvers = {
  Subscription: {
    postCreated: {
      subscribe: () => pubsub.asyncIterator(['POST_CREATED'])
    }
  },
  Mutation: {
    createPost: async (_, { input }) => {
      const post = await db.createPost(input);
      pubsub.publish('POST_CREATED', { postCreated: post });
      return { post };
    }
  }
};

N+1 Problem and DataLoader

The N+1 Problem

Example: Fetching 10 posts with authors

// This resolver is called 10 times (once per post)
Post: {
  author: async (post, args, context) => {
    // N+1: 1 query for posts + 10 queries for authors
    return await db.query('SELECT * FROM users WHERE id = ?', [post.authorId]);
  }
}

Result: 11 database queries (inefficient)

DataLoader Solution

DataLoader batches and caches requests within a single request

const DataLoader = require('dataloader');

// Batch function: receives array of IDs, returns array of users
const batchGetUsers = async (userIds) => {
  const users = await db.query(
    'SELECT * FROM users WHERE id IN (?)',
    [userIds]
  );

  // CRITICAL: Return users in same order as userIds
  const userMap = new Map(users.map(u => [u.id, u]));
  return userIds.map(id => userMap.get(id) || new Error('Not found'));
};

// Create DataLoader in context (per-request)
context: ({ req }) => ({
  loaders: {
    userLoader: new DataLoader(batchGetUsers)
  }
})

// Use in resolver
Post: {
  author: async (post, args, context) => {
    // DataLoader batches all calls and executes once
    return await context.loaders.userLoader.load(post.authorId);
  }
}

Result: 2 database queries (1 for posts + 1 batched for authors)

DataLoader Best Practices

// ✅ CORRECT: Create loaders in context (per-request)
context: ({ req }) => ({
  loaders: {
    userLoader: new DataLoader(batchGetUsers),
    postLoader: new DataLoader(batchGetPosts)
  }
})

// ❌ WRONG: Global DataLoader (caches across requests)
const globalUserLoader = new DataLoader(batchGetUsers);  // Memory leak!

// ✅ CORRECT: Return array in same order as input
const batchGetUsers = async (ids) => {
  const users = await fetchUsers(ids);
  const userMap = new Map(users.map(u => [u.id, u]));
  return ids.map(id => userMap.get(id) || new Error('Not found'));
};

Error Handling

User Errors (Validation)

Mutation: {
  createPost: async (parent, { input }, context) => {
    const errors = [];

    if (input.title.length < 5) {
      errors.push({ field: 'title', message: 'Title too short' });
    }

    if (input.content.length < 20) {
      errors.push({ field: 'content', message: 'Content too short' });
    }

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

    const post = await db.createPost(input);
    return { post, errors: [] };
  }
}

System Errors (Unexpected)

const { AuthenticationError, UserInputError } = require('apollo-server');

Query: {
  user: async (parent, { id }, context) => {
    if (!context.user) {
      throw new AuthenticationError('Must be logged in');
    }

    if (!id.match(/^\d+$/)) {
      throw new UserInputError('Invalid ID format');
    }

    return await db.getUserById(id);
  }
}

Pagination

type Query {
  posts(first: Int = 10, after: String): PostConnection!
}

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}

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

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}

Implementation:

Query: {
  posts: async (parent, { first = 10, after }) => {
    const cursor = after ? decodeCursor(after) : 0;

    // Fetch one extra to check hasNextPage
    const posts = await db.query(
      'SELECT * FROM posts WHERE id > ? ORDER BY id ASC LIMIT ?',
      [cursor, first + 1]
    );

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

    const edges = nodes.map(post => ({
      node: post,
      cursor: encodeCursor(post.id)
    }));

    return {
      edges,
      pageInfo: {
        hasNextPage,
        endCursor: edges[edges.length - 1]?.cursor
      }
    };
  }
}

const encodeCursor = (id) => Buffer.from(id.toString()).toString('base64');
const decodeCursor = (cursor) => parseInt(Buffer.from(cursor, 'base64').toString());

Pros: Consistent results, efficient for large datasets Cons: Can't jump to arbitrary page

Offset Pagination (Simpler)

type Query {
  posts(limit: Int = 10, offset: Int = 0): PostPage!
}

type PostPage {
  items: [Post!]!
  total: Int!
}

Pros: Simple, can jump to page N Cons: Inconsistent if data changes, slow for large offsets


Authorization

Field-Level Authorization

const resolvers = {
  Query: {
    users: async (parent, args, context) => {
      // Query-level auth
      if (!context.user?.isAdmin) {
        throw new AuthenticationError('Admin only');
      }
      return await db.getUsers();
    }
  },

  User: {
    email: (user, args, context) => {
      // Field-level auth (hide email from non-owners)
      if (context.user?.id !== user.id && !context.user?.isAdmin) {
        return null;
      }
      return user.email;
    }
  }
};

Directive-Based Authorization

directive @auth(requires: Role = USER) on FIELD_DEFINITION

enum Role {
  USER
  ADMIN
}

type Query {
  posts: [Post!]!
  users: [User!]! @auth(requires: ADMIN)
}

type User {
  id: ID!
  name: String!
  email: String! @auth(requires: USER)
}

Schema Patterns

Interface (Polymorphism)

interface Searchable {
  id: ID!
  title: String!
}

type Post implements Searchable {
  id: ID!
  title: String!
  content: String!
}

type Video implements Searchable {
  id: ID!
  title: String!
  url: String!
}

type Query {
  search(query: String!): [Searchable!]!
}

Resolver:

Searchable: {
  __resolveType(obj) {
    if (obj.content) return 'Post';
    if (obj.url) return 'Video';
    return null;
  }
}

Union (Flexible Results)

union SearchResult = Post | Video | User

type Query {
  search(query: String!): [SearchResult!]!
}

Client query:

query Search($query: String!) {
  search(query: $query) {
    __typename
    ... on Post { title content }
    ... on Video { title url }
    ... on User { name email }
  }
}

Common Anti-Patterns

Anti-Pattern Problem Solution
N+1 queries Not using DataLoader Batch with DataLoader
Deep queries No depth limits validationRules: [depthLimit(5)]
Large lists No pagination Use cursor pagination
Scalar mutations deletePost: Boolean Return payload object
Global DataLoader Caches across requests Create per-request in context
No error handling Throw on validation Return errors in payload
Logic in resolvers Business logic mixed Resolvers call service layer

Level 3: Resources

Reference Documentation

Location: skills/api/graphql-schema-design/resources/REFERENCE.md

Comprehensive 900+ line reference covering:

  • GraphQL schema design principles and best practices
  • Complete type system (scalars, objects, interfaces, unions, enums, inputs)
  • Schema patterns (Node, Connection, Payload, Error types)
  • Query and mutation design with examples
  • Subscription patterns for real-time updates
  • Error handling strategies and types
  • Pagination (offset-based, cursor-based, Relay connections)
  • Performance optimization (DataLoader, complexity analysis, caching)
  • Security (authentication, authorization, rate limiting, validation)
  • Schema versioning and deprecation strategies
  • Schema federation and stitching
  • Testing strategies for schemas
  • Complete anti-patterns catalog

Executable Scripts

Location: skills/api/graphql-schema-design/resources/scripts/

  1. analyze_schema.py - GraphQL schema analyzer

    • Analyzes GraphQL schemas for anti-patterns and best practices
    • Detects naming convention violations
    • Checks documentation coverage
    • Validates pagination patterns
    • Identifies nullability issues
    • Checks mutation design patterns
    • Calculates quality score (0-100)
    • Output: Human-readable report or JSON
    ./analyze_schema.py schema.graphql
    ./analyze_schema.py schema.graphql --json
    ./analyze_schema.py schema.graphql --min-score 80
    
  2. generate_types.py - TypeScript type generator

    • Generates TypeScript type definitions from GraphQL schemas
    • Supports all GraphQL type system features
    • Handles custom scalars, enums, interfaces, unions
    • Configurable nullability handling
    • JSON output for programmatic use
    • Output: TypeScript .d.ts file or JSON
    ./generate_types.py schema.graphql -o types.ts
    ./generate_types.py schema.graphql --nullable-by-default
    ./generate_types.py schema.graphql --json
    
  3. benchmark_queries.js - GraphQL query benchmarking tool

    • Benchmarks GraphQL query performance
    • Concurrent request support
    • Detailed timing metrics (min, max, avg, p50, p90, p95, p99)
    • Throughput calculation (requests/sec)
    • Payload size analysis
    • Warmup phase support
    • Custom headers and authentication
    • JSON output for CI/CD integration
    ./benchmark_queries.js -e http://localhost:4000/graphql -q "{ users { id } }"
    ./benchmark_queries.js -e http://localhost:4000/graphql --query-file query.graphql -c 10 -i 100
    ./benchmark_queries.js -e http://localhost:4000/graphql -q "{ posts { title } }" --json
    

Code Examples

Location: skills/api/graphql-schema-design/resources/examples/

  1. python/graphql_server.py - Strawberry GraphQL server

    • Complete GraphQL server using Strawberry (Python)
    • Type-safe schema with Python type hints
    • DataLoader for N+1 prevention
    • Connection-based pagination
    • Error handling with union types
    • Authentication and authorization
    • Input types and payload types
    • Runnable example with FastAPI
  2. typescript/graphql_server.ts - Apollo Server implementation

    • Complete GraphQL server using Apollo Server
    • Type-safe resolvers with TypeScript
    • DataLoader batching patterns
    • Relay-style pagination
    • Error handling with interfaces
    • Context-based authentication
    • Subscription support
    • Runnable standalone server
  3. typescript/graphql_client.ts - Apollo Client implementation

    • Complete GraphQL client using Apollo Client
    • Type-safe queries and mutations
    • Fragment composition
    • Cache management strategies
    • Pagination handling
    • Optimistic updates
    • Real-time query watching
    • Error handling patterns
  4. schemas/good-schema.graphql - Best practices schema

    • Production-ready schema demonstrating all best practices
    • Complete documentation for all types and fields
    • Proper naming conventions (PascalCase, camelCase, SCREAMING_SNAKE_CASE)
    • Node interface for global object identification
    • Relay connection pattern for pagination
    • Error handling with interface types
    • Input types for all mutations
    • Payload types with success/errors fields
    • Custom scalars (DateTime, Email, URL, UUID)
    • Comprehensive type system usage
  5. schemas/anti-patterns.graphql - Anti-patterns catalog

    • Comprehensive catalog of 30+ GraphQL anti-patterns
    • Each pattern documented with explanation
    • Shows incorrect approaches with comments
    • Covers naming, structure, performance, and design issues
    • Use as negative reference ("what NOT to do")

Usage

All scripts are executable and include --help:

cd skills/api/graphql-schema-design/resources/scripts
./analyze_schema.py --help
./generate_types.py --help
./benchmark_queries.js --help

Examples are runnable with dependencies installed:

# Python server
cd examples/python
pip install strawberry-graphql fastapi uvicorn
python graphql_server.py

# TypeScript server
cd examples/typescript
npm install @apollo/server dataloader
ts-node graphql_server.ts

# TypeScript client
cd examples/typescript
npm install @apollo/client
ts-node graphql_client.ts

  • rest-api-design.md - Comparing REST vs GraphQL
  • dataloader-optimization.md - Advanced DataLoader patterns
  • postgres-query-optimization.md - Optimizing database queries
  • api-authentication.md - JWT and OAuth patterns

Last Updated: 2025-10-27 Format Version: 1.0 (Atomic)