A Comprehensive Overview of GraphQL Federation in Open Source

Welcome! If you're new to GraphQL Federation or looking to understand its fundamentals, you're in the right place. As Stefan Avram , I focus on creating content that bridges the gap between beginner and intermediate developers, making complex concepts more approachable.

For more advanced, deep-dive content on GraphQL Federation, I recommend checking out the technical articles from my co founders Jens Neuse and Dustin Dues .

GraphQL has revolutionized the way developers build and consume APIs, GraphQL and the underlying Query API style is especially powerful when you're building a distributed API layer that spans across more than one service. As GraphQL adoption continues to grow, organizations are seeking ways to scale their GraphQL APIs while maintaining a modular and manageable codebase.

Enter GraphQL Federation—a powerful architecture that enables teams to create and manage large-scale GraphQL APIs by composing smaller, independently developed GraphQL services called Subgraphs. By embracing a federated approach, companies can harness the full potential of GraphQL while ensuring their API infrastructure remains agile and performant.

In this article, we'll explore the concepts behind GraphQL Federation, its benefits for development teams, and how open-source tools and specifications are driving innovation in this space. We'll also look at the wider landscape of federation tools, enterprise concerns, schema governance, and a concrete path to getting started.

GraphQL Federation is an architectural pattern that allows developers to create a single, unified GraphQL API, known as a Federated Graph, by combining multiple smaller GraphQL APIs called Subgraphs. This modular approach enables teams to work independently on different parts of the overall schema, promoting faster development cycles and reducing the risk of conflicts.

At its core, GraphQL Federation is designed to support microservice architectures, where each Subgraph encapsulates a specific domain or functionality. By exposing a unified GraphQL API to clients, Federation abstracts away the complexity of the underlying microservices, providing a seamless and coherent experience for API consumers.

The Federated Graph, also known as Supergraph, composed of all the types and fields from each Subgraph schema, acts as a single entry point for clients to interact with the federated GraphQL API. This composition is made possible by a centralized component, often referred to as the Router, which sits between the clients and the Subgraphs, orchestrating the execution of incoming requests and merging the results from the relevant Subgraphs.

Before we go further, let's pin down the vocabulary you'll see throughout this article:

• Subgraph: a single, independent GraphQL service that owns one domain (for example, products or users).
• Supergraph: the unified schema composed from all your Subgraphs—the one API clients actually talk to.
• Router: the component that receives a client query, figures out which Subgraphs to call, and merges the results.
• Query planner: the logic inside the Router that decides the most efficient path to resolve a query across Subgraphs.
• Schema registry: a central place where Subgraph schemas are published, versioned, and composed into the Supergraph.
• Schema checks: automated validation that catches breaking changes before a new schema is published.

GraphQL Federation relies on the integration of distinct Subgraphs and a central orchestrator. Each Subgraph operates independently as a fully functional GraphQL server, with its own schema, resolvers, and data sources. This independence allows development teams to focus on their specific domains, enabling parallel development and reducing interdependencies. The encapsulation of functionality within Subgraphs ensures that updates or modifications remain isolated, thus maintaining stability across the broader API ecosystem.

The orchestrator, often termed the Router, is essential in managing and directing client queries. It processes incoming requests and decomposes them into targeted operations that individual Subgraphs can handle. By leveraging advanced query planning techniques, the Router ensures efficient execution across the federated system, thereby optimizing performance and response times. The quality of that query plan matters a lot—a smarter planner means fewer round trips to your Subgraphs and faster responses.

A unified schema, derived from the aggregation of all Subgraph schemas, underpins the Router's functionality. This schema serves as a comprehensive map that informs the Router about which Subgraph should resolve specific fields. By doing so, the Router can efficiently route and merge data from various sources, presenting clients with a seamless interface that abstracts the intricacies of the federated backend. This cohesive approach allows the API to deliver a consistent and reliable experience to its consumers.

GraphQL Federation provides substantial benefits for development teams, particularly in complex projects where maintaining modularity is crucial. A key advantage lies in the capability of teams to focus on their specific domains without interference from other parts of the system. This isolation not only fosters an environment where teams can innovate within their domain but also contributes to a more streamlined workflow by reducing dependencies and potential bottlenecks.

The architecture supports diverse technology stacks, allowing teams to choose the most effective tools and frameworks for their specific requirements. This adaptability means that teams can tailor their development processes to align with their expertise and project needs, enhancing both productivity and creativity. Such flexibility is essential in dynamic environments where the ability to quickly pivot and adopt new technologies can be a significant differentiator.

The federated approach curtails the typical challenges associated with monolithic GraphQL APIs, such as complex merge processes and coordination delays. By allowing Subgraphs to evolve independently, updates and new functionalities can be integrated more swiftly. This is also why Federation is such a natural destination for a growing GraphQL API: when a single monolithic schema starts to creak under the weight of many teams, splitting it into Subgraphs relieves the pressure. If that's the road you're on, my colleagues wrote a great guide on the transition from a monolithic to a federated GraphQL architecture .

The maintained single request-response cycle through the Router ensures that clients benefit from a streamlined and efficient querying experience. This design preserves the simplicity of interacting with a single endpoint while harnessing the distributed power of the underlying federated architecture. As a result, development teams can deliver robust and scalable solutions that meet the demands of modern applications. This isn't limited to request-response either—real-time use cases like subscriptions and streaming can flow through the same federated graph, which is exactly what Cosmo Streams is built to handle.

Here's something that surprises newcomers: Federation isn't one product. It's a pattern, and there are several open-source and source-available stacks that implement it today. The three you're most likely to run into are Cosmo, Apollo, and Hive.

• Cosmo Router is Apache 2.0 licensed and written in Go. Its sweet spot is the self-host, platform-engineering story: drop the binary into your own Kubernetes cluster or VPC, point it at your Supergraph, and you're in full control. No SaaS dependency required.
• Apollo Router / Apollo Federation is the most widely-used name in the space. The Apollo Router is source-available under a commercial-friendly license, and it's closely tied to Apollo's GraphOS / SaaS control plane. If you're already invested in Apollo's ecosystem, it's a well-trodden path.
• Hive Gateway/Router by The Guild is an open-source federation gateway within the Hive ecosystem, a popular choice among teams who like The Guild's broader open-source GraphQL tooling.

Here's a quick side-by-side to keep the trade-offs straight:

All three are legitimate choices, and the "right" one really does depend on your context. That said, if your priorities are open-source licensing, a polyglot backend, and the ability to fully self-host without leaning on a vendor's SaaS, Cosmo tends to fit those constraints particularly cleanly.

Federation looks great on a whiteboard. Then you take it to a large organization and a different set of questions shows up—the ones platform and security teams care about. Let's tackle them head-on.

In bigger orgs, "can it federate?" is quickly followed by "does it meet our compliance bar?" Expectations around SOC 2, ISO 27001, and HIPAA are common, and they aren't checkboxes you bolt on at the end.

This is precisely where a self-hostable, Apache 2.0 router like Cosmo earns its keep: you keep the data plane inside your own infrastructure while still getting a managed-feeling control plane experience.

Here's the reality in most enterprises: not everything is GraphQL. You've got REST services, gRPC microservices, databases, and a long tail of internal systems built over many years. Telling all of those teams to "just stand up a GraphQL server" is a non-starter.

This is where Cosmo Connect comes in. It lets you bring non-GraphQL backends—REST, gRPC, and more—into the federated graph without forcing every team to adopt GraphQL servers on day one. The platform team gets a unified federated API; the backend teams keep shipping in the stack they already know.

If you've ever tried to roll out Federation across an org, you've met the REST-first team—the folks who, very reasonably, don't want to rewrite working APIs just to satisfy an architecture diagram. Their resistance isn't stubbornness; rewrites are risky and expensive.

The nice thing about a Cosmo-style approach is that it sidesteps the standoff:

• Platform teams get to expose a single, unified federated API to consumers.
• Backend teams (REST, gRPC, and friends) keep their existing stacks and participate in the graph gradually, on their own timeline.

Nobody has to bet the quarter on a big-bang migration. Teams opt in as it makes sense, which is usually the only way large-scale adoption actually happens.

Once more than a couple of teams are shipping changes to the same Supergraph, you need a way to keep it safe and stable. That's schema governance in plain terms: making sure the graph stays healthy as many people push changes to it.

The scariest failure mode is the breaking change—a field removed, a type renamed, an argument made required—that slips into production and takes a client app down with it. The whole game is to catch those before they're published, not to debug them after customers start seeing errors. Put bluntly: you want to stop a bad schema from ever getting published, rather than fixing it after production errors.

Cosmo handles this with schema checks. In Cosmo Studio , you can see exactly what a proposed change would do to the Supergraph—what breaks, what's safe, and who's affected. The real power, though, is wiring those checks into your pipeline. Running wgc subgraph check in CI validates a Subgraph's proposed schema against the composed graph and fails the build if it would introduce a breaking change. That means a risky schema never gets published in the first place—the safety net lives in the pull request, not in production.

In practice, this turns schema safety into a routine part of code review. A developer opens a PR, CI runs the check, and if the change is breaking, they find out in minutes instead of in an incident channel later.

Enough theory—let’s talk about actually shipping a federated graph. The fastest way I know to go from nothing to a running Supergraph is the From Zero to Federation in 5 Steps Using Cosmo tutorial. Here’s the journey in my own words:

• Install the Cosmo CLI and clone the demo. You install wgc, clone the cosmo-demo repository, and cd into it; this gives you two example Subgraphs (Posts and Users) plus a Router setup.
• Start the demo Subgraphs locally. You run the provided script to bring up the posts and users GraphQL services on localhost, and verify each one responds on its own port.
• Compose a router configuration. Using wgc router compose and the included graph.localhost.yaml, you generate a config.json that describes your composed federated graph.
• Run Cosmo Router with that config. You start the Router in Docker, mounting config.json and exposing a single unified GraphQL endpoint on localhost:3002.
• Send queries to your federated graph. With the Router running, you can make real queries (for example, posts with author details) against the Supergraph and see data stitched across Subgraphs.

From there, you can grow into the full workflow—publishing subgraph schemas, running wgc subgraph check in CI, and letting a registry‑backed Supergraph power your production router.

That’s the core arc: start from a single graph, introduce Subgraphs, and layer on governance until you have a production‑ready federated API. If you started life as a single monolithic GraphQL server, the same path applies; just treat that server as your first Subgraph and grow from there (the monolith-to-federation guide is a handy companion for that move).

As GraphQL Federation continues to evolve, driven by the power of open-source innovation, it's clear that this architectural pattern will play a pivotal role in shaping the future of API development. By embracing the principles of modularity, flexibility, and collaboration, organizations can unlock the full potential of their GraphQL APIs, delivering scalable and performant solutions that meet the demands of modern applications.

In our next blog post, we'll dive deep into the best practices for implementing GraphQL Federation, covering everything from Subgraph design principles to schema validation strategies. Stay tuned to learn how to make the most of your federated architecture!

If you're ready to start your GraphQL Federation journey today, we invite you to get started for free with our open-source solution and experience the transformative power of this innovative approach firsthand.