First GraphQL API

Apollo or Hasura.

Overview

The first GraphQL API is the point where API design moves from REST resources to client-driven queries. The benefits (typed clients, single round-trip, no over-fetching) come paired with real operational costs (resolver-level n+1, runaway query depth, the temptation to expose arbitrary database access). Doing GraphQL well means accepting both sides on day one.

• Apollo or Hasura. Code-first server (Apollo) or DB-first auto-generation (Hasura). Different starting points for different workloads.
• Schema as contract. SDL defines the API surface. Typed clients fall out of the schema; documentation comes free.
• Resolver-per-field. Lazy field resolution lets clients ask for what they need. Without care, the same flexibility creates n+1 query patterns.
• Persisted queries plus complexity limits. Production should not accept arbitrary queries; per-query depth and cost limits prevent runaway resolver chains.

The approach

Three habits make a first GraphQL API operationally tractable: schema-first design, persisted queries in production, and complexity limits enforced at the gateway.

• Schema first. SDL drives client and server generation. The schema is the source of truth, not the implementation.
• Persisted queries in production. Pre-registered allowlist of approved queries. Production never sees arbitrary client queries.
• Complexity limits. Per-query depth and cost ceiling. Runaway nested queries get rejected at the gateway.
• Resolver-level instrumentation plus schema docs. Per-resolver tracing surfaces the n+1 patterns; per-type documentation supports adoption.

Why this compounds

Each schema iteration deepens the team’s API design instincts. Typed clients spread across the codebase; the schema becomes a source of truth that survives engineering turnover.

• Client experience improves. Client-driven queries cut over-fetching and reduce round trips. Mobile clients particularly benefit.
• Contract clarity. SDL is the single source of truth. Frontend and backend align on the same artefact.
• Operational stability. Persisted queries and complexity limits prevent the most common GraphQL outage modes.
• Year-one investment, year-two habit. First schema is heavy lift. By the third, schema design is muscle memory.