Feature: GraphQL API

New API surface.

Overview

The Nova GraphQL API ships alongside the existing REST surface. The shape that survives production: schema-first design, persisted queries in production, and explicit complexity limits per query.

• GraphQL alongside REST. Both surfaces coexist. Clients pick the one that fits their query shape.
• Schema as contract. SDL defines the API. Typed clients (TypeScript, Swift, Kotlin) generate from the schema rather than handwriting types.
• Per-field resolvers. Lazy field resolution lets clients ask for exactly what they need. Avoids the over-fetching that REST encourages.
• Persisted queries plus complexity limits. Production allowlists pre-registered queries; per-query complexity limits cap the cost of any single request.

The approach

Three habits keep GraphQL operationally sound: SDL drives client generation, production accepts only persisted queries, and every query carries a complexity ceiling.

• Schema first. SDL is the source of truth. Type generation runs in CI; drift between server and client cannot ship.
• Persisted queries in prod. Production accepts only pre-registered query hashes. Ad-hoc queries belong to staging.
• Complexity limits. Per-query depth and cost ceilings. A single rogue query cannot exhaust the database.
• Per-resolver instrumentation. Resolver-level tracing surfaces the slow field. Investigation has the right granularity.

Why this compounds

The first schema takes design effort; subsequent additions reuse the toolchain. Within a year, the GraphQL surface is a first-class citizen alongside REST.

• Client experience. Client-driven queries reduce over-fetching and round-trips. Mobile clients especially benefit.
• Contract clarity. SDL is the single source of truth for client and server. Mismatches surface at type-check time.
• Operational stability. Persisted queries plus complexity limits produce predictable load. Production cannot be surprised by a new query shape.
• Year-one investment, year-two habit. The first schema design is the heavy lift. Subsequent additions are well-trodden territory.