TL;DR
GraphQL federation is an architectural pattern that combines multiple independently developed GraphQL services, called subgraphs, into a single unified API called a supergraph. A router builds a query plan and orchestrates requests across those subgraphs, so clients can query the whole system as if it were one schema. Because each team owns its own subgraph, federation is as much an organizational model as a runtime one.
Glossary
Supergraph
The unified schema clients query, composed from multiple subgraph schemas; the public surface of the federated system.
Clients see one API even when many teams own the backend services behind it.
Subgraph
An independent GraphQL service that owns a portion of the supergraph schema; the unit of team ownership.
Teams can ship domain changes without centralizing all backend development.
Router
The gateway that plans queries, fetches data from subgraphs, and assembles the response; the runtime hot path for every query.
Router quality determines latency and operational visibility; batching and caching behavior depend on the implementation.
Schema registry
The system of record for subgraph schemas and composition results; it validates whether schemas compose safely before they reach production.
Breaking composition can be caught in CI instead of during live traffic.
Composition
In composition-based federation, the process of merging subgraph schemas into a single supergraph ahead of execution rather than during request handling.
Schema conflicts can surface during composition or CI, before live traffic hits the graph.
Entity
A type that spans multiple subgraphs, identified in federation by a `@key` directive; the mechanism that lets one graph object be extended across service boundaries.
Shared types like User or Product can be owned in parts by different teams.
What Is GraphQL Federation?
GraphQL federation is an architectural pattern that combines multiple independently developed schemas, called subgraphs, into a single unified API called a supergraph. A router (or gateway) builds a query plan and orchestrates requests across those subgraphs so clients can query the system as if it were one schema.
Depending on your setup, a subgraph might be a traditional GraphQL server or a virtual schema generated from other backends, such as gRPC or REST services, as long as it participates in the federated composition process.
In practice, federation is as much an organizational model as a runtime model. Teams can own separate domains and still contribute to a shared graph, which makes federation especially useful when a single API has to reflect the structure and ownership boundaries of multiple backend teams.
What sets schema-composition-based federation apart from a simple proxying gateway:
- In composition-based setups, subgraph schemas are composed and validated before being rolled out to the router, so many incompatibilities can be caught before they ever affect production traffic.
- The router builds a schema-aware query plan and then orchestrates distributed execution across subgraphs, instead of simply proxying requests to a single backend. Planning behavior and optimizations vary by implementation.
- Entities can span services, so a single type like User or Product can be defined and extended across multiple subgraphs, while teams establish clear ownership conventions for who defines which parts of the type.
Platforms like WunderGraph Cosmo add governance tools and composition rules on top of federation to help enforce those ownership conventions across teams.
How Does GraphQL Federation Work?
Four core mechanics drive most federated graphs: schema composition, federation directives, query planning, and entity resolution. They are not an exhaustive picture of runtime behavior, but understanding them is the difference between wiring up federation and operating it well in production.
Schema composition
In composition-based setups, each subgraph's schema is registered with a central schema registry, usually via CI pipelines or CLI tooling. The registry composes these subgraph schemas into a supergraph and validates whether they form a consistent, compatible graph before new configurations are rolled out to the router.
That design matters operationally. Instead of discovering conflicts when a client query hits production, teams can fail schema changes during CI or review workflows and only publish a new supergraph once composition checks pass.
Mature federation platforms build governance and change-management features on top of this composition step.
Federation directives
Most federation implementations use schema directives to describe entity identity, cross-subgraph relationships, and routing and execution behavior.
In the Apollo / Open Federation family, core directives include @key (entity identity), @external, @requires, and @provides, with Federation v2 adding @shareable, @override, @interfaceObject, and others.
Cosmo implements an open, Apollo-compatible set of federation directives and adds platform-specific ones for governance, security, and documentation control. For the full list of directives, version-specific rules, and examples, see the Federation Directives index in the Cosmo docs.
Query planning
When the router receives a query, it validates it against the supergraph schema and builds a query plan. That plan determines which subgraphs to call, which fetches can run in parallel, and how to join the results back into one response.
Depending on the implementation, advanced routers may also batch subgraph requests, cache query plans, deduplicate fetches, and emit detailed tracing so operators can understand why a query behaved the way it did.
Platforms like WunderGraph Cosmo go further with features such as query-plan caching and cache warmers that precompute plans for operations that are slow to plan.
Entity resolution
Entity resolution is what lets a single graph object span service boundaries. If one subgraph owns `User.name` and another owns `User.orders`, the router can fetch an entity key (via a representation query like `_entities`) from the first service and use it to resolve related fields from the second.
This is one of federation's biggest strengths and one of its main performance risks. Without effective batching and smart query planning, which some routers implement and others do not, clean graph queries can devolve into slow internal fan-out.
That is why query planning, observability, and tracing matter so much in production.
Request flow, end to end
- The client sends a single GraphQL query to the router.
- The router validates it against the supergraph schema it loaded from the CDN and retrieves or computes a query plan.
- The router sends the necessary subgraph requests, batching and parallelizing where the plan allows.
- Each subgraph returns its slice of the response.
- The router assembles the result and returns one response to the client.
What Changes When GraphQL Federation Scales Across Teams?
Federation looks straightforward with a few subgraphs. It becomes much harder when many teams are publishing schema changes into the same production graph.
At scale, the hard part shifts from composition alone to the operating model around composition. Platform teams need ownership rules, review workflows, observability, and a reliable way to answer basic questions like which supergraph version is live and which clients still depend on a given field.
Common failure modes include:
- Schema changes break trust when teams cannot coordinate safely.
- Governance overhead grows when ownership and deprecation policies are informal.
- Query performance degrades when entity resolution fans out without effective batching.
- Observability gaps appear when traces stop at the gateway.
- Subscription complexity grows when connection state and delivery logic spread across services (for example, whether the router coordinates subscriptions or each subgraph manages its own connections).
None of these problems mean federation is the wrong architectural choice. They point to a gap the spec does not cover. Composition merges schemas, but it does nothing for the human coordination around those schemas: finding the team that owns a type, agreeing on a field, and tracking the change.
That coordination tax is where federation programs actually slow down.
Federation doesn't enforce a design direction. Subgraph teams can build their pieces independently and let the supergraph emerge from composition. Or teams can design the consumer-facing API first and work backward.
In practice, most organizations do both at once, and the supergraph ends up a side effect of composition rather than something deliberately designed.
Cosmo is built for that reality. Schema checks, guardrails, distributed tracing, and governance extend beyond composition into the runtime, and Hub gives frontend and backend teams a shared place to design and agree on the graph before anything ships.
Platform teams can see and control how the supergraph behaves in production without becoming the bottleneck for every change.
When Is GraphQL Federation the Wrong Choice?
Federation is demanding infrastructure. It tends to pay for itself when multiple teams need to evolve one shared API surface, and it often costs more than it returns when that coordination problem does not yet exist.
A practical rule of thumb is that federation starts to become compelling when several teams need independent ownership over a shared API contract. Below that threshold, a modular monolith, schema stitching, or a client-specific BFF layer is often the better tradeoff.
- One or two teams with a small API surface. A modular monolith is often simpler to operate.
- Services that do not share entities across team boundaries.
- Backends that don't justify the cost of exposing them through a shared GraphQL contract yet.
From BFF to Federation
The Backend-for-Frontend pattern puts a dedicated gateway between each client type and the backend. Each BFF shapes data for its specific client: the mobile BFF returns compact payloads, the web BFF returns richer objects.
For a small number of clients and a contained backend, this is a reasonable design.
Problems tend to appear as the backend and client surface grow. Multiple BFFs end up integrating the same services.
User profile logic gets written once in the mobile BFF and again in the web BFF. When the user service changes, both owners update.
Add a third client type and the pattern extends: another BFF, another copy of the same integrations, another team to coordinate with when something changes upstream.
At that point, teams are paying a coordination cost twice: once when backend services change, and once when clients want different data shapes.
Federation addresses the duplication by putting one shared, typed contract (the supergraph schema) between the backend and all clients. Subgraph teams own their domain; the router handles assembly.
Clients still query what they need, but the integration logic is shared and governed rather than copied across BFFs.
Signs a BFF is ready to be consolidated into a federated graph:
- Multiple BFFs integrate the same backend services independently.
- Schema drift across client-specific APIs exposing the same underlying domain data.
- Backend changes require coordinating the same update across multiple BFF owners.
- A new client type would mean building another full integration layer from scratch.
- No central view of the full API surface across all clients.
SoundCloud and Luxury Presence both ran into this wall and moved onto a federated graph on WunderGraph Cosmo. SoundCloud is the company that helped popularize the BFF pattern.
How Does GraphQL Federation Compare to Schema Stitching?
Both present multiple services through one GraphQL API. The difference is in how cross-service relationships are expressed and validated, not in whether stitching is always “runtime-only.”
| Schema stitching | GraphQL Federation | |
|---|---|---|
| How schemas combine | Via a gateway using delegation and schema extension patterns, often with build-time or gateway-side logic | Composed ahead of execution in a registry or composition pipeline |
| Cross-service relationships | Commonly expressed in gateway delegation logic | Declared in the schema with federation directives and the composition model |
| Schema conflicts | May surface at runtime depending on setup | Often caught during composition or CI before deployment |
| Often better suited for | Smaller systems, single-team API ownership | Multiple teams that need explicit entity boundaries |
Stitching remains a valid pattern for smaller systems and centralized ownership. Federation tends to be a better fit when multiple teams need reviewable cross-subgraph contracts, including entity directives and clear ownership boundaries.
Cosmo focuses on GraphQL federation and composite schema patterns rather than traditional stitching, so cross-service relationships and contracts live in your schemas, not in bespoke gateway code.
How Does GraphQL Federation Compare to a REST API Gateway?
The two operate at different layers and often coexist.
| REST / edge gateway | GraphQL Federation router | |
|---|---|---|
| What it exposes | Backend endpoints | A unified typed schema |
| Primary job | Routing, auth, rate limiting | Query planning, data composition, and schema-aware routing |
| Can they coexist? | Yes. A REST gateway can sit in front of a federation router. | Yes. Typically deployed behind an edge gateway. |
In many deployments, Cosmo's router runs behind an existing REST or edge gateway, combining GraphQL query planning with your existing traffic and security controls.
What Are the Benefits of GraphQL Federation?
Federation is worth the operational overhead when it solves a real coordination problem: multiple teams evolving one shared API without fragmenting the client experience.
Those benefits are real, but they are not automatic. Federation amplifies both good schema design and bad schema design, which is why successful programs treat schema quality as a core engineering concern, not as after-the-fact cleanup.
- Team autonomy through domain-based subgraph ownership.
- One unified API surface for clients.
- Design-time (pre-publication) validation of schema compatibility in composition-based setups, via a registry and schema checks.
- Better alignment between organizational ownership and API structure.
- A path to shared observability and centralized graph governance when paired with a platform that provides tracing, metrics, and schema checks.
What Do Successful GraphQL Federation Programs Need Beyond Composition?
The open mechanics of federation explain how schemas compose and how routers execute queries. They do not, by themselves, solve the full operating problem of running a shared graph in production.
This is where product differences matter more than spec differences. Teams rarely struggle with the abstract idea of federation; they struggle with operating it safely as the number of teams, services, and schema changes grows.
- A schema registry that validates compatibility before publication.
- Governance: ownership rules, review workflows, and controlled deprecations.
- A query planner whose output is inspectable and regression-tested, so you can understand and optimize how queries fan out across subgraphs.
- Distributed tracing from the router into subgraphs.
- A way to include non-GraphQL services without rewriting them. This is platform-specific; Cosmo Connect is WunderGraph's approach to exposing gRPC, REST, and other backends as part of the supergraph.
The Federation Stack
Composition and a router contract are where the open spec ends. Everything else that keeps a shared graph healthy in production sits outside it.
At scale, federation works as a stack: a set of components that each own one layer of the problem and hand work to the next.
Schema changes start in a design and governance layer, where teams agree on the contract and a registry validates that the schemas still compose.
The composed supergraph then reaches the runtime, where a router plans and executes queries across subgraphs on the hot path for every request.
Integration components bring non-GraphQL and event-driven backends into the same graph, so the router can resolve them alongside native subgraphs.
Four layers carry most of that load:
- Runtime. The router plans queries, executes them across subgraphs, and exposes tracing and metrics for every request.
- Design and governance. Teams design the schema, the registry validates composition, and ownership and deprecation rules are enforced before a change ships.
- Multi-protocol integration. gRPC, REST, and other non-GraphQL backends join the supergraph without being rewritten as native subgraphs.
- Event-driven subscriptions. The router connects to event systems so federated subscriptions work without spreading connection state across services.
The sections that follow walk through how WunderGraph Cosmo implements each layer.
What WunderGraph Adds Beyond the Spec
WunderGraph Cosmo is an open-source federation platform built for the operating layer the spec leaves out. It adds schema checks, governance guardrails, distributed tracing, multi-protocol integration, and self-hosted or managed deployment. These are the parts that matter once a federated graph goes to production.
Router performance and query planning
Cosmo Router is built in Go with auth integration, subscriptions, and observability built in. In our benchmark comparisons against Apollo Router on cold query-planning workloads, Cosmo Router has shown significantly lower P99 latency.
Outcomes depend on workload, hardware, router configuration, and methodology. Treat any single benchmark as a data point, not a universal truth.
WunderGraph attributes Cosmo Router's performance in those tests to its Go-based execution planner, breadth-first batching, single-flight deduplication of in-flight subgraph fetches, and query-plan caching.
Deterministic query normalization helps too: semantically identical queries can reuse the same cached plan. These details matter in federated production workloads, where the router sits on the request path for every query.
The router is open-source and available in the WunderGraph Cosmo GitHub repository. See WunderGraph's published benchmark harness for methodology and full numbers.
Governance through Hub
Hub is the collaboration layer federation leaves out. It replaces the ad hoc mix of Slack threads, Miro boards, and design meetings teams use to coordinate schema changes today.
Hub's schema engine, Fission, inverts the standard federation workflow: teams design the consumer-facing API first, starting from a "dream query" that describes what a client needs.
Fission takes those assignments and generates each subgraph's schema automatically: entity keys, federation directives, and cross-subgraph references included.
Frontend teams can describe the query they wish they could write. Backend teams can see what consumers need. Platform teams can run schema checks, enforce guardrails around breaking changes, and manage ownership and deprecation across subgraphs.
Nothing merges until affected subgraph owners approve. Individual teams move quickly without breaking the shared graph, and without routing every change through a central bottleneck.
gRPC and REST federation with Cosmo Connect
Cosmo Connect brings non-GraphQL backends (gRPC services, REST APIs, legacy systems) into federation without requiring those teams to adopt GraphQL. ConnectRPC runs the other direction: it takes your GraphQL operations and exposes them as REST endpoints, OpenAPI specs, and type-safe SDKs for consumers who don't use GraphQL.
Many production environments are multi-protocol. A federation platform that assumes every service will eventually become a native GraphQL subgraph creates more migration work than most teams will accept, which is why WunderGraph offers both as alternative paths.
Event-driven subscriptions with Cosmo Streams
GraphQL federation does not define one universal subscription execution model. Implementations differ widely. Cosmo Streams is WunderGraph's event-driven approach to subscriptions in federated graphs: the router subscribes to Kafka, NATS, or Redis directly, and in that model subgraphs can remain stateless. When an event arrives, the router fetches the required data from subgraphs over plain HTTP requests.
That design targets a common federated-subscriptions pain point (connection overhead and subscription state spreading across services), but it is Cosmo-specific architecture, not something every federation stack provides.
How Does GraphQL Federation Work With AI Agents and MCP?
A federated supergraph is a typed, governed, queryable surface across many internal systems. Those properties are useful for AI agents, because typed operations, explicit schemas, and centralized routing can make tool exposure safer and easier to reason about.
Cosmo now includes two MCP capabilities. The MCP Gateway is a router feature that exposes your GraphQL operations as tools AI agents can call at runtime.
The Cosmo MCP Server is a separate IDE integration that lets developers use AI assistants (Claude, Cursor, Windsurf, VS Code) to manage schemas and subgraphs during development.
This is a concrete emerging capability, not a settled industry standard.
A well-governed supergraph can be a strong substrate for AI tooling: one typed interface over fragmented backend services, with shared access policy and visibility into what agents are calling.
How Do You Get Started With GraphQL Federation?
Cosmo has a free tier and full documentation for both managed and self-hosted deployment. Basic evaluation setups can often be created quickly; time to value depends on how many services you federate, schema maturity, and operational requirements.
- Create or identify the first subgraph.
- Publish subgraph schemas into a schema registry and composition workflow.
- Compose the supergraph and validate compatibility via schema checks.
- Deploy a router against the composed graph.
- Start querying the unified API from clients.
Who Uses GraphQL Federation?
Federation is used across media, marketplaces, travel, SaaS, and platform engineering teams. The broad appeal is the same across industries: multiple teams need to contribute to one API without centralizing all backend development in one service.
These WunderGraph customers run federation in production:
500K requests per second
Eliminated BFF sprawl and scaled their API landscape across 20+ subgraph-owning teams with WunderGraph Cosmo.
Read case study
86% CPU reduction
Cut compute from 600 to 80 vCPUs, saved an estimated $265,000 annually, and reduced monthly infrastructure cost from about $14,000 to about $9,750.
Read case study
$178K saved
Avoided building and maintaining custom federation capabilities in-house, with estimated savings on development and long-term support.
Read case study
Tens of ms faster at peak
Advanced Request Tracing into federated queries cut debugging time and reduced latency during peak traffic after migrating from a monolith.
Read case study
10s down to under 1s
Cache warming eliminated repeated 10+ second query planning delays on the slowest operations, helping the team scale more predictably during traffic spikes.
Read case study
40 deploys per day
Replaced BFF layers with federation across 70+ engineers, sharing logic in one graph and shrinking code review from three PRs per feature to one or two.
Read case study
HIPAA-compliant self-hosting
Hosts the Cosmo router inside their own infrastructure so sensitive healthcare data never leaves their environment, with schema checks catching breaking changes in CI.
Read case study
Migration in about one day
Moved from Apollo to Cosmo in roughly a day, gained faster complex queries, and fixed federation schema issues their previous provider had missed.
Read case study
PCI-compliant federation
Uses a self-hosted router and namespace filtering to keep PCI data in the federated graph while exposing only safe fields to client applications.
Read case study
Production in about 10 days
Deployed Cosmo into production in roughly ten days, gaining multiple client endpoints through one router with full observability across their stack.
Read case studyFrequently Asked Questions
Learn More About GraphQL Federation
Getting started
Architecture deep dives
Performance and scaling
Features and capabilities
Comparisons
Start Building With GraphQL Federation
If your team is running or scaling a federated graph, Cosmo gives you the governance, observability, and protocol flexibility to run it well. It is open-source, free to start, and available self-hosted or managed.
Published June 8, 2026 · WunderGraph
