GraphQL

01Schemas, types and resolvers

Think of a REST API as a set menu: each endpoint returns a fixed plate. GraphQL is a buffet with a precise order form: the client lists the dishes and portions it wants. The server describes everything available in a schema written in the Schema Definition Language (SDL). Object types (Product, Order) have fields with types; scalars are the basics (String, Int, Boolean, ID); the exclamation mark means non-null; lists use brackets. Special root types define entry points: Query for reads, Mutation for writes, Subscription for real-time updates. Each field is backed by a resolver, a function that returns its value. The server parses a query, validates it against the schema, then calls resolvers field by field, building a response that mirrors the shape of the query. Unknown fields are rejected before any code runs.

1type Product {
2  id: ID!
3  name: String!
4  price: Int!
5  category: Category!
6}
7 
8type Category {
9  id: ID!
10  name: String!
11}
12 
13type Query {
14  products(first: Int = 20, after: String): [Product!]!
15  product(id: ID!): Product
16}
17 
18type Mutation {
19  renameProduct(id: ID!, name: String!): Product!
20}

02Queries, mutations and subscriptions

A query asks for data; the client chooses fields and can follow relationships in one request, such as products with their category names. Variables keep queries static and reusable, which also enables persisted queries. Fragments reuse field selections across components, and many client libraries colocate them with UI components. A mutation changes data and returns the updated object, so the client cache can refresh without another request; mutations in one request run in sequence. Design mutations around business actions (placeOrder, cancelSubscription) rather than generic table updates, and return structured errors for expected failures, such as validation, inside the payload. Subscriptions push updates to the client, typically over WebSockets or server-sent events, for things like order status or chat. They add stateful connections to scale and secure, so use them where live updates truly matter.

03The N+1 problem and DataLoader

Because each field has its own resolver, a naive server runs one query for the list of 50 products and then one query per product for its category: 51 queries for one request. That is the N+1 problem, and nested queries make it worse. The standard fix is batching with DataLoader. Instead of fetching immediately, each resolver asks a loader for a key; the loader collects all keys requested in the same tick of the event loop and fetches them with one query (WHERE id IN ...), then returns results in the right order. It also caches per request, so the same category is loaded once. Create loaders per request, never globally, so cached data cannot leak between users. Monitor resolver timings and query counts per operation to catch regressions.

1import DataLoader from "dataloader";
2 
3// One set of loaders per request, so caching never leaks between users
4export function createLoaders(db: Db) {
5  return {
6    categoryById: new DataLoader<string, Category | null>(async (ids) => {
7      const rows = await db.category.findMany({ where: { id: { in: [...ids] } } });
8      const byId = new Map(rows.map((c) => [c.id, c]));
9      return ids.map((id) => byId.get(id) ?? null);
10    }),
11  };
12}
13 
14export const resolvers = {
15  Product: {
16    category: (p: Product, _args: unknown, ctx: Ctx) =>
17      ctx.loaders.categoryById.load(p.categoryId),
18  },
19};

04Caching and security

REST benefits from HTTP caching: each URL is a resource that browsers, CDNs and proxies can cache. GraphQL usually sends POST requests to a single endpoint, so that layer disappears. The answers: normalised client caches (Apollo Client, urql, Relay) that store objects by type and ID; persisted queries sent as GET with a hash, which makes CDN caching possible again; and server-side caching of resolver results with careful per-user scoping. Security needs equal care. A client can write a deeply nested or huge query that costs the server a fortune, so enforce maximum depth, query complexity or cost limits, pagination limits and timeouts. Rate limit by cost, not just request count. In production, consider disabling introspection for private APIs or, better, allow only persisted queries from your own clients. Authorise in resolvers or a business layer, per field where needed, never only at the endpoint.

• Depth and complexity limits, plus required pagination on lists.
• Persisted queries: smaller requests, CDN caching, a safe allow-list.
• Field-level authorisation and per-request DataLoaders.

05GraphQL vs REST vs tRPC

Choose by client landscape and team setup. GraphQL wins when many clients with different needs share a rich, connected domain, when a platform team serves several product teams, or when you aggregate several backends into one graph (federation). REST wins for public APIs, simple resource models, file uploads and downloads, webhooks and anything that benefits from HTTP caching and familiar tooling; with OpenAPI you still get typed clients. tRPC wins in TypeScript monorepos where the same team owns server and client: procedures are called like functions with end-to-end types and almost no schema overhead, but it is TypeScript-only and not meant as a public, language-neutral API. Many systems mix them: REST or tRPC for internal apps, a public REST API for partners, and GraphQL only where its flexibility pays for its complexity.

06Execution internals: nullability and partial results

A GraphQL response can contain both data and errors. When a resolver throws, the error is added to the errors array with a path to the failing field, and that field becomes null. If the field is declared non-null, null is not allowed, so the null bubbles up to the nearest nullable parent, possibly wiping out a whole list or the entire data object. That makes nullability a design decision, not decoration. Mark fields non-null when they are truly always present and cheap (id, name), and keep fields nullable when they depend on another service or permission check, so one failure degrades a single field rather than the page. Clients must handle partial data. Resolver execution order also matters: sibling fields of a query may resolve in parallel, while top-level mutation fields run serially.

• Errors carry a path; the failing field becomes null.
• Non-null fields propagate nulls upward to the nearest nullable parent.
• Make fields that call fragile dependencies nullable.

07Cost analysis and pagination at scale

Depth limits alone are weak: a shallow query asking for 100 products, each with 100 reviews, each with 100 authors, can request a million objects. Static cost analysis assigns a cost to each field, multiplies list fields by their requested page size, and rejects queries above a budget before execution. Publish the cost in a response extension so clients can see it, and rate limit by cost per minute. Make pagination mandatory with a maximum page size. The cursor-based connections pattern (edges, node, pageInfo with endCursor and hasNextPage) is the de facto standard: cursors are opaque, stable under inserts and avoid the deep OFFSET scans that slow databases down. Encode the sort key and ID in the cursor, and use a keyset query (WHERE (created_at, id) < (...) ORDER BY created_at DESC, id DESC) underneath.

1type ProductConnection {
2  edges: [ProductEdge!]!
3  pageInfo: PageInfo!
4}
5 
6type ProductEdge {
7  cursor: String!
8  node: Product!
9}
10 
11type PageInfo {
12  hasNextPage: Boolean!
13  endCursor: String
14}
15 
16type Query {
17  products(first: Int! = 20, after: String): ProductConnection!
18}

08Federation: one graph from many services

Federation lets several teams each own a subgraph while clients see one supergraph. A subgraph declares entities with a key, for example a Product identified by id. Another subgraph can extend that entity with its own fields, such as reviews, and provides a reference resolver that loads a product's extra data given only its key. A router composes the subgraph schemas, plans each incoming query, calls subgraphs in the right order, often in parallel, and stitches results together. This keeps team autonomy while giving clients a single API. The costs: composition checks in CI become critical, because one subgraph can break the supergraph; query plans can fan out into many internal calls, so entity resolvers must batch; and debugging needs tracing through the router. It suits organisations with several backend teams; for a single team it is overhead.

09Errors as data, input design and newer spec features

Use the errors array for unexpected failures, and model expected business outcomes in the schema. A mutation can return a union such as PlaceOrderResult = OrderPlaced | OutOfStock | PaymentDeclined, and clients handle each case with fragments, getting typed fields for every outcome. Design inputs per action: placeOrder(input: PlaceOrderInput!) keeps arguments evolvable. The September 2025 edition of the GraphQL specification, the first since 2021, added OneOf input objects, where exactly one field must be provided, which neatly models 'find a product by id or by sku'. Incremental delivery with @defer and @stream, which lets slow parts of a response arrive later, is supported by several servers and clients but still moving through the specification process, so check your stack's support before relying on it.

1union PlaceOrderResult = OrderPlaced | OutOfStock | PaymentDeclined
2 
3type OrderPlaced { order: Order! }
4type OutOfStock { productIds: [ID!]! }
5type PaymentDeclined { reason: String! }
6 
7input ProductLookup @oneOf {
8  id: ID
9  sku: String
10}
11 
12type Mutation {
13  placeOrder(input: PlaceOrderInput!): PlaceOrderResult!
14}
15 
16type Query {
17  product(by: ProductLookup!): Product
18}