GraphQL Schema Design Template for PMs

GraphQL is a strong fit when your frontend needs flexible queries across related entities, when mobile bandwidth is a constraint, or when multiple clients need different subsets of the same data. REST is simpler when your API is primarily CRUD on flat resources, when HTTP caching is critical, or when most consumers are external partners who prefer predictable endpoints. See the [REST API glossary entry](/glossary/rest-api) for when REST is the better choice.

Implement three safeguards: query depth limiting (reject queries nested deeper than 5-7 levels), query complexity analysis (assign cost weights to fields and reject queries that exceed a budget), and DataLoader batching (prevent N+1 queries on relationship fields). Together these prevent both accidental and malicious expensive queries.

Both work. Union types (`Success | ValidationError | NotFoundError`) give consumers type-safe error handling in their generated client code. Error extensions (`errors[].extensions.code`) are simpler to implement and more familiar to teams coming from REST. Pick one pattern and use it consistently. Mixing both in the same schema creates confusion.

GraphQL schemas are forward-compatible by default. Adding new types, fields, and enum values never breaks existing queries. Removing or renaming fields is a breaking change. Use the `@deprecated` directive to signal that a field will be removed, then track usage in your analytics to know when it is safe to drop. Never remove a field that still has active consumers.

Most production schemas cap depth at 5-7 levels. Deeper than that usually indicates a schema design problem (too many nested relationships) or a consumer making an inefficient query. Start at 5 and increase only if legitimate use cases require it. Log rejected queries so you can distinguish between abuse and genuine need. ---