REST API to GraphQL Federation Blueprint

What and Why

REST APIs often grow into dozens of endpoints, each returning fixed payloads. Clients over-fetch or chain calls, and mobile teams suffer. GraphQL gives clients a single typed endpoint where they request exactly the fields they need. Federation (the Apollo Federation model) lets each service own a slice of one combined graph, so teams stay independent while clients see one schema.

This blueprint migrates a REST estate to a federated GraphQL graph incrementally. You keep REST running while you stand up the graph, then move clients over feature by feature.

Phases

Assessment. Inventory every REST endpoint, its consumers, auth model, and traffic. Identify high-chattiness flows (screens that call five endpoints) as first migration targets. Map REST resources to GraphQL types.

Schema design. Define the supergraph: entities, fields, and which subgraph owns each. Apply schema-first design and a naming convention. Resolve N+1 risk early by planning DataLoader batching against your REST or database layer.

Gateway setup. Stand up a GraphQL gateway (Apollo Router or equivalent) in front of subgraphs. Each subgraph wraps existing REST calls or talks to the database directly. Wire OAuth 2.0 / OIDC token validation at the gateway.

Incremental migration. Use the strangler-fig pattern: GraphQL resolvers initially proxy the live REST endpoints (an anti-corruption layer). Migrate resolvers to call data sources directly once stable. Add persisted queries to cap query cost.

Client cutover. Move clients screen by screen. Keep REST live until traffic drops to zero, then deprecate per the backward-compatibility policy.

Key Risks and Mitigations

• N+1 queries: every resolver hitting REST per item multiplies load. Use DataLoader batching and per-request caching, and load-test the worst nested query.
• Skills gap: GraphQL schema modeling and resolver performance are new skills. Pair backend engineers, run a schema review, and adopt a linter (graphql-eslint).
• Schema sprawl: uncontrolled type growth makes the graph unusable. Enforce schema review, deprecation tags, and a federation registry with CI checks.

Recommended Tooling

Apollo Router or GraphQL Mesh for the gateway, Apollo Federation for subgraph composition, DataLoader for batching, Redis for response and persisted-query caching, and a schema registry with CI composition checks. Instrument resolver latency with OpenTelemetry.

Success Metrics

Track payload-size reduction versus the old REST flows, the number of round trips per screen (target one), resolver p95 latency, and feature lead time once teams own subgraphs.

Prerequisites

A documented REST surface (ideally OpenAPI), stable auth via OAuth/OIDC, and a service that can host the gateway. Teams should agree on entity ownership before writing the first subgraph.