GraphQL Design Guide

Problem

GraphQL APIs modeled too closely after database tables often run into the same issues: nested fields trigger N+1 queries, large lists suffer when using offset pagination, mutations return data without a consistent error shape, and schema files grow into a monolith. This skill turns those problems into concrete design constraints, making it useful before adding endpoints, refactoring resolvers, or reviewing a schema.

How It Works

It centers on schema design, resolvers, and subscriptions. List fields should use Relay-style connections for cursor pagination. Batched entity lookups should use DataLoader, with fresh instances created per request to avoid stale or cross-user cache state. Mutations should return payload types containing both result and errors, while mutation arguments use Input types. The guidance also emphasizes splitting the schema into domain-specific modules and configuring query depth and complexity limits to reduce the risk of unbounded queries.

Boundaries

This material is best used as a design or review checklist for API design, code review, and team standards, especially when a team needs consistent GraphQL rules. It does not replace runtime concerns such as authorization, caching, gateway rate limiting, or subscription infrastructure. For complex multi-tenant or federated schemas, validate the recommendations against your framework and operational constraints.