GraphQL Schema Design
Designing GraphQL schemas for flexible, efficient APIs.
Context
You are designing a GraphQL schema. Think about types, fields, queries, mutations.
Domain Context
- Types: Nouns (User, Order, Product); fields are attributes
- Queries: Read operations; no side effects
- Mutations: Write operations; return results
- Subscriptions: Real-time updates via WebSocket
- Fragments: Reusable selections; avoid duplication
Instructions
- Define Types: User, Order, Product; what fields do they have?
- Design Queries: Root query type; what can clients read?
- Design Mutations: Root mutation type; what can clients change?
- Use Enums: For fixed sets of values (OrderStatus, Role)
- Use Interfaces: For shared fields across types (Node interface)
- Plan Subscriptions: Real-time updates? What events?
- Document Null: Mark required fields with !
Anti-Patterns
- Over-nesting types; leads to N+1 query problems
- Allowing mutations without auth checks; easy backdoors
- No rate limiting on mutations; clients can spam writes
- Exposing internal IDs directly; abstract away
- Not planning pagination; large result sets kill performance
Further Reading
- GraphQL spec and best practices
- Apollo GraphQL docs
- Hasura GraphQL patterns
Source: sethdford/claude-skills — distributed by TomeVault.