What Is GraphQL Federation?

Yilia Lin

Yilia Lin

November 12, 2025

Technology

Key Takeaways

  • The Problem: Microservice architectures often lead to "API sprawl," forcing front-end developers to chase data across dozens of REST endpoints to build a single UI component.
  • The Evolution: A traditional API gateway organizes traffic, but a federated graph organizes data. It's a data composition layer that unifies all your backend services (GraphQL, REST, gRPC) into a single GraphQL API.
  • Apollo Federation: This is the de-facto standard for building a federated graph. It uses subgraphs (domain-specific services) which are composed into a supergraph (the unified schema).
  • Complementary, Not Competitive: A federated gateway (like the Apollo Router) excels at data routing. It lives behind an edge API gateway (like Apache APISIX), which handles cross-cutting concerns like authentication, security, and general traffic management.

Beyond the Gateway: From API Sprawl to a Unified Data Graph

We broke down the monolith into microservices to gain development speed and autonomous scaling, but in its place, we often created a new problem: REST API sprawl. Front-end developers are now forced to become distributed systems experts, chasing data across dozens of different microservice APIs to build a single screen in an application. The client is left to orchestrate the calls and stitch the data together.

The first-generation solution to this complexity was the API Gateway. A gateway like Apache APISIX solved the crucial "front door" problem. It provided a single, unified entry point for routing, authentication, rate-limiting, and security. It successfully organized the traffic flowing into our systems.

However, a lingering problem remained: data composition. While a gateway organizes traffic, it doesn't inherently solve the data aggregation problem for the client. The client app still has to make multiple calls—GET /users/{id}, GET /products/{id}/details, GET /reviews?productId={id}—and then manually join that data on the front end.

This is where the next evolution in API architecture comes in. A federated graph is a single, unified GraphQL API that acts as a powerful data composition layer. It sits above all your existing services (GraphQL, REST, gRPC, databases) and logically composes them into one cohesive "graph of everything." Your clients can now make one declarative GraphQL query and get exactly the data they need in a single round trip, no matter how many disparate services it lives in.

The Case for Federation: Why Build a 'Graph of Everything'?

The adoption of GraphQL Federation by enterprises is driven by tangible benefits that address the core pains of modern application development at scale.

1. Unparalleled Developer Experience (DX) This is the primary driver. With a federated supergraph, front-end developers are given a superpower: a single, self-documenting endpoint for all the organization's data.

  • No more over-fetching or under-fetching: They can request precisely the fields they need for a component—the product's name and price from the Products service, and the user's name from the Users service—all in one query. This dramatically improves front-end performance and simplifies client-side state management.
  • One GraphQL query replaces dozens of REST calls: Instead of writing complex client-side orchestration logic, a developer can write a single, easy-to-read query. This massively accelerates feature development and reduces the cognitive load on client teams.

2. Decoupled Development at Scale Federation allows backend teams to achieve the true promise of microservices: autonomous ownership.

  • The "Users" team can build, manage, and deploy their Users subgraph completely independently. The "Products" team owns their Products subgraph, and so on.
  • As long as a team doesn't make a breaking change to their public subgraph schema, they can deploy their service at any time without coordinating with other teams. The federated gateway handles composing the schemas in real time.

3. Incremental Adoption and Legacy Modernization A federated graph is not a disruptive "rip and replace" strategy. It's a powerful abstraction layer that you build on top of your existing infrastructure.

  • You can start small by federating just two services and grow the supergraph from there.
  • Crucially, you can bring non-GraphQL services into the graph. Legacy REST APIs, gRPC services, and even direct database sources can be wrapped in a simple adapter and exposed as a subgraph. This presents them to clients as if they were native GraphQL, providing a clear and practical path for modernizing legacy systems without risky, large-scale rewrites.

How It Works: The Architecture of Apollo Federation

The de-facto standard for building a federated graph is Apollo Federation. It provides a clear specification and a suite of tools for implementing this architecture.

The Core Components

  1. Subgraph: An independent GraphQL service with its own schema that represents a single business domain (e.g., Products, Reviews, Users). Each subgraph is a complete, runnable service.
  2. Supergraph: The single, composed GraphQL schema that is automatically generated from all your subgraphs. This is the schema that your API clients interact with. It does not have its own business logic; it's a "read-only" composition of the underlying subgraphs.
  3. Federated Gateway (Router): The high-performance runtime (like the Apollo Router) that receives queries against the supergraph. It's responsible for creating an intelligent query plan to fetch the necessary data from the correct subgraphs and compose the final JSON result for the client.

The Magic: Linking Types Across Subgraphs

The real power of federation comes from its ability to link and extend types across different service boundaries. This is accomplished with a few simple GraphQL directives. A Product type can be defined in the Products subgraph and then extended in the Reviews subgraph to add new fields.

  • @key(fields: "..."): This directive designates a type as a federated "entity." It specifies the primary key (e.g., id or upc) that can be used by other subgraphs to reference it.
  • @extends and @external: A subgraph can extend an entity defined in another subgraph. To do so, it uses the @extends directive and marks the fields it needs from the original service as @external.

Example: Imagine a Products service and a Reviews service.

# products_subgraph.graphql
# This subgraph defines the base Product entity.
type Product @key(fields: "id") {
  id: ID!
  name: String!
  price: Float!
  upc: String!
}

# reviews_subgraph.graphql
# This subgraph extends the Product entity to add reviews.
type Product @key(fields: "id") @extends {
  id: ID! @external # We need the Product's id to look it up.
  reviews: [Review!]
}

type Review {
  id: ID!
  rating: Int!
  body: String!
}

The federated gateway understands these directives. When it sees them, it knows that the Product type is a single entity whose fields are split across two different microservices.

The Query Plan in Action

When a client sends a query, the federated gateway creates a query plan.

sequenceDiagram
    participant Client
    participant Gateway as Federated Gateway
    participant Products as Products Subgraph
    participant Reviews as Reviews Subgraph

    Client->>Gateway: Query { product(id: "1") { name reviews { rating } } }
    note right of Gateway: Gateway creates a query plan.
    Gateway->>Products: { product(id: "1") { name id } }
    Products-->>Gateway: { product: { name: "Standing Desk", id: "1" } }
    note right of Gateway: Now get data for the extended fields.
    Gateway->>Reviews: { _entities(representations:[{__typename:"Product", id:"1"}]) { ... on Product { reviews { rating } } } }
    Reviews-->>Gateway: { _entities: [ { reviews: [...] } ] }
    note right of Gateway: Compose the results and return.
    Gateway-->>Client: { data: { product: { name: "Standing Desk", reviews: [...] } } }

Governance with the Rover CLI

A supergraph is a shared resource that many teams contribute to. How do you prevent one team from accidentally pushing a change that breaks everyone else? This is where governance tools like the Apollo Rover CLI become essential. Rover is a command-line tool for managing your federated graph, often integrated into a CI/CD pipeline, allowing you to:

  • Validate subgraph schemas: Ensure a new subgraph schema follows federation rules.
  • Check for breaking changes: Running rover subgraph check before merging a pull request compares a proposed subgraph change against the production supergraph to detect and prevent breaking changes.
  • Publish schemas to a registry: The schema registry (like Apollo Studio) acts as the source of truth for your supergraph's composition.

API Gateway + Federated Graph: A Complementary Architecture

A common point of confusion is whether a federated graph replaces an edge API gateway. The answer is a definitive no. They perform different, complementary jobs.

  • An Edge API Gateway (like Apache APISIX) is a general-purpose traffic manager. It is the single front door for your entire organization. Its job is to handle cross-cutting L7 concerns like SSL termination, client authentication (JWT/OAuth), WAF security, IP restriction, and routing traffic to any kind of upstream service.
  • A Federated Gateway (like the Apollo Router) is a specialized data router. Its single, focused job is to understand GraphQL, create query plans, fetch data from subgraphs, and compose GraphQL responses.

The federated gateway should almost always live behind the edge gateway.

graph LR
    subgraph "External"
        C[Client Apps]
        P[Partner Systems]
    end

    GW(Edge Gateway<br/>)

    subgraph "Internal Services"
        FG(Federated Gateway<br/><i>Apollo</i>)
        S1[Products]
        S2[Reviews]
        S3[REST Adapter]
        LR[Legacy API]
        F[File Upload]
    end

    C --> GW
    P --> GW
    GW --> FG
    GW --> F
    FG --> S1
    FG --> S2
    FG --> S3
    S3 --> LR

This architecture provides the best of both worlds. The edge gateway secures the perimeter and manages all traffic, while the federated gateway handles the complex task of data composition, providing a clean, unified data layer for your applications.

Conclusion: Weaving the Graph of Everything

The move from monolithic applications to microservices solved one problem but created another: a chaotic web of APIs that burdened client applications with immense complexity. The federated graph, powered by standards like Apollo Federation, represents the next logical step in taming this complexity. It is not just another API; it is a data composition system that provides a unified, logical view across all your distributed data sources.

By offering a superior developer experience, enabling true backend decoupling, and providing a practical path for legacy modernization, GraphQL Federation is shifting from a niche pattern to a mainstream enterprise architecture. The "Graph of Everything" is no longer a theoretical concept; it's an achievable architectural destination. It acknowledges that your Edge API Gateway manages the front door, while your Federated Graph organizes the data within the house. Together, they create a a secure, scalable, and remarkably agile digital platform.

Tags:
API Gateway Basics