architecture-descriptionestablished · high operational burden

GraphQL Federation

Also known as: federated-graphql, apollo-federation, graphql-gateway

Intent

Compose multiple GraphQL services into a single unified graph, enabling independent service ownership with unified client queries.

Problem

Monolithic GraphQL schema couples teams. Schema stitching is manual. Need autonomous services with unified query layer.

Forces

•Teams own domains (Users, Orders, Products)
•Clients need cross-domain queries (user + orders + products)
•Schema changes must not break other teams
•Gateway must be performant (query planning, caching)

Solution

✓ When to Use

•Multiple teams owning GraphQL services
•Clients need cross-domain queries
•Schema evolution without coordination

✗ When Not to Use

•Single team, single GraphQL service
•Simple REST APIs sufficient
•Team not ready for GraphQL complexity

Pros

+Team autonomy: own schema, deploy independently
+Unified client experience: single query, single endpoint
+Entity references: join across services without client logic
+Schema registry: breaking change detection

Cons

−Gateway complexity: query planning, caching, error handling
−N+1 risk: gateway must batch entity resolution
−Debugging: distributed traces across subgraphs
−Schema design: entity keys, ownership boundaries

Cost Profile

Infrastructure

Medium — gateway, registry, subgraph hosting

Operational

High — schema registry, query analysis, performance

Cognitive

High — federation concepts, entity design

Failure Modes

Subgraph down → partial schema, gateway errors
N+1 queries: entity resolution not batched
Schema conflict: two subgraphs define same type
Gateway OOM: large query planning
Breaking change undetected: registry not checked

Real-World Examples

Alternatives

schema-stitching
bff
rest-gateway
graphql-gateway

Related Patterns

api-gateway
bff
schema-registry
consumer-driven-contracts
graphql

Competency Domains

distribution communicationdeploymentreliability opseconomics evolution