⬡ GraphQL Advanced

How do you design a scalable GraphQL schema?

Answer

Scalable schema design principles: (1) Follow the Relay spec: global IDs (Node interface), cursor pagination (Connection/Edge), single input argument mutations. (2) Verb-noun mutation naming: createPost, updateUser, deleteComment — clear and consistent. (3) Rich payloads: mutations return payload objects, not just the modified entity — allows adding fields (e.g., errors, userErrors) without breaking changes. (4) Nullability by design: be conservative with non-null — easy to make nullable fields non-null later (non-breaking), hard to reverse. (5) Abstract types: use interfaces for shared structures, unions for heterogeneous results. (6) Avoid over-normalization: don't model every database relation as a GraphQL type — model the client's needs. (7) Never expose internal IDs: use opaque global IDs. (8) Version by field deprecation: add new fields, deprecate old ones — no versioning needed. (9) Think about mutations atomically: each mutation should be a single business operation.