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
Cursor-Based Pagination (Recommended)
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/
-
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 -
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 -
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/
-
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
-
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
-
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
-
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
-
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
Related Skills
rest-api-design.md- Comparing REST vs GraphQLdataloader-optimization.md- Advanced DataLoader patternspostgres-query-optimization.md- Optimizing database queriesapi-authentication.md- JWT and OAuth patterns
Last Updated: 2025-10-27 Format Version: 1.0 (Atomic)