Production APIs Playbook — Part 3 of 5

GraphQL is loved for one reason: it gives clients flexibility. But in production, that same flexibility can become your biggest risk—slow queries, heavy payloads, and unpredictable performance.

If you want GraphQL that scales, the goal is simple: make performance and behavior predictable while keeping the developer experience clean.

1) Start with a schema that represents the product, not the database

The most common GraphQL mistake is mirroring tables: UserTable, OrderRow, ProductEntity. That locks you into today’s storage design and creates painful breaking changes later.

Better approach: model what the client needs:

• User, Order, Product, Cart, PaymentMethod

• Think in “business objects” with stable names and stable meaning

Rule: Your schema is a public contract. Treat it like an API, not an ORM.

2) The N+1 problem is not “a GraphQL issue”—it’s a resolver design issue

In GraphQL, a single query can trigger dozens (or hundreds) of resolver calls. If each resolver makes its own database call, production traffic will destroy you.

What good teams do:

• Batch requests per request-cycle

• Cache repeated loads per request

• Fetch data in “sets,” not one-by-one

That’s why DataLoader exists.

3) DataLoader: the production default

DataLoader groups many “load by id” operations into one batch call.

What it gives you:

• Batching: turn 50 DB calls into 1–3 calls

• Per-request caching: avoid duplicate lookups inside the same query

• Cleaner resolver code: resolvers become simple, predictable

Important: DataLoader caching is per request, not global. That’s good—because you avoid stale cross-user caching by default.

4) Pagination that won’t break later

Offset pagination (page=3&limit=20) is easy—but can produce duplicates/missing items when data changes.

Production-safe pattern:

• Cursor-based pagination for feeds and large lists

• Enforce a max page size

• Make ordering explicit and stable

Rule: Never allow unlimited list queries in production.

5) Caching: GraphQL caching is possible—just do it intentionally

GraphQL doesn’t automatically mean “no caching.” It means you need to decide where caching belongs.

Common production strategies:

• Cache at the data layer (fast lookups, reference data, computed aggregates)

• Cache resolver results for expensive fields (per request)

• Cache persisted queries at the edge/CDN (when clients use known queries)

• Cache “read-heavy endpoints” with controlled query shapes

The key is controlling query shapes and complexity so caches become reliable.

6) Query complexity limits (the hidden lifesaver)

GraphQL allows nested queries. Without limits, someone can request massive graphs and force your API to do extreme work.

Production defenses:

• Max depth (stop crazy nesting)

• Max complexity / cost

• Max response size or max nodes returned

• Rate limiting per user/client key

• Persisted queries for public clients

This is how you keep GraphQL flexible without turning it into a denial-of-service machine.

7) Error handling: be consistent, or clients will suffer

GraphQL returns data and errors. In production, you need a clear rule:

• What errors are “user errors” vs “system errors”?

• When does the API return partial data?

• Do you expose internal details? (usually no)

Best practice:

• Return clean, stable error codes (e.g., UNAUTHENTICATED, FORBIDDEN, VALIDATION_ERROR)

• Keep messages user-safe

• Log the real details server-side with trace IDs

Rule: Clients need predictable behavior. Ops needs deep visibility.

A simple production checklist (copy/paste mental model)

Before shipping GraphQL to production, verify:

• Schema models product concepts (not DB tables)

• DataLoader used for common “load by id” patterns

• Cursor pagination + max page size enforced

• Complexity/depth limits exist

• Persisted queries or query allowlist for public clients

• Error codes are stable and documented

• Tracing/logging includes resolver timings and slow query signals

What’s next in the series

Part 4/5 is the “senior decision”: gRPC vs REST—deadlines, streaming, and service-to-service design that avoids incidents.