Implement GraphQL API Runner

Build a production-ready GraphQL API with schema design, optimized resolvers, DataLoader integration, real-time subscriptions, and security controls for your detected framework.

When to Use This Command

Run this command when...

• You need to implement a GraphQL API from scratch with type definitions, queries, mutations, and subscriptions
• You want DataLoader integration to prevent N+1 query problems and optimize database access patterns
• You need real-time capabilities with WebSocket subscriptions for live data updates
• You are building a federated GraphQL architecture with Apollo Federation or schema stitching
• You want query complexity analysis, depth limiting, and rate limiting to protect your GraphQL endpoint

Quick Start

Copy
# .claude/commands/implement-graphql-api-runner.yaml
name: Implement GraphQL API Runner
description: Build production-ready GraphQL API with resolvers and subscriptions
inputs:
  - name: approach
    description: "schema-first, code-first, or federation"
    default: "schema-first"

Copy
# Build schema-first GraphQL API
claude "implement-graphql-api --approach schema-first"

# Build with Apollo Federation
claude "implement-graphql-api --approach federation --services users,products,orders"

Output:
  [detect] Framework: Apollo Server 4 (Express)
  [schema] Designed 6 types, 12 queries, 8 mutations, 3 subscriptions
  [resolvers] Generated resolvers with DataLoader integration
  [auth] Added JWT context and field-level authorization
  [security] Query depth limit: 10, complexity limit: 1000
  [playground] GraphQL Playground enabled at /graphql
  Done. GraphQL API ready with 29 operations.

Core Concepts

Concept	Description
Schema Design	Type definitions with custom scalars, enums, interfaces, and union types for expressive data modeling
Resolver Architecture	Modular resolvers with authentication context, error handling, and database abstraction
DataLoader Pattern	Batch loading and per-request caching to eliminate N+1 queries across resolver chains
Subscriptions	WebSocket-based real-time updates using pub/sub patterns for live data streaming
Query Protection	Depth limiting, complexity scoring, and rate limiting to prevent abuse and resource exhaustion

GraphQL Architecture:
  Client
    │
  ┌─▼──────────────┐
  │  GraphQL Layer  │
  ├─────────────────┤
  │ Schema          │    ┌────────────┐
  │ ├── Queries     │───>│ Resolvers  │
  │ ├── Mutations   │    │ ├── Auth   │
  │ └── Subscriptions    │ ├── CRUD   │
  └─────────────────┘    │ └── Sub    │
                         └─────┬──────┘
                               │
                         ┌─────▼──────┐
                         │ DataLoader │
                         │ (Batching) │
                         └─────┬──────┘
                               │
                         ┌─────▼──────┐
                         │  Database  │
                         └────────────┘

Configuration

Parameter	Type	Default	Description
approach	string	"schema-first"	Architecture: schema-first, code-first, or federation
services	string	""	Comma-separated federated service names (for federation approach)
subscriptions	boolean	true	Enable WebSocket subscriptions for real-time features
depth_limit	integer	10	Maximum allowed query nesting depth
complexity_limit	integer	1000	Maximum query complexity score before rejection

Best Practices

1. Use DataLoader everywhere -- Every resolver that accesses a database should go through a DataLoader. This prevents the N+1 problem that is especially severe in GraphQL due to nested resolvers.
2. Implement field-level authorization -- Do not rely solely on endpoint-level auth. Use GraphQL directives or resolver middleware to check permissions per field, especially for sensitive data.
3. Set conservative query limits -- Start with depth limit 10 and complexity 1000. Monitor actual query patterns in production and adjust upward only when legitimate use cases demand it.
4. Version through schema evolution -- GraphQL APIs should not be versioned like REST. Instead, deprecate fields with @deprecated and add new fields alongside old ones for backward compatibility.
5. Enable introspection only in development -- Disable schema introspection in production to prevent attackers from discovering your full API surface. Keep it enabled in dev for tooling.

Common Issues

1. N+1 queries despite DataLoader -- DataLoader batches within a single tick. If resolvers use async/await incorrectly, batching windows may not align. Verify that DataLoader keys are collected before any await.
2. Subscription memory leaks -- WebSocket connections that are not properly cleaned up consume server memory. Implement connection timeout handling and graceful disconnect logic.
3. Schema stitching conflicts -- Federated services with overlapping type names cause merge errors. Use the @key directive and explicit type extensions to resolve ownership conflicts.