What is GraphQL Federation? A practical guide for modern APIs

As applications grow more complex, so do their APIs. Teams often split large monolithic GraphQL schemas into modular, independent services. But how do you stitch them back together into a single, seamless API for your clients?

This is where GraphQL Federation comes in.

In this guide, we’ll break down what GraphQL Federation is, why it matters, and how modern platforms like Grafbase simplify federation for developers.

GraphQL Federation is an architectural pattern that allows multiple GraphQL services (also called subgraphs) to work together as a single unified GraphQL API.

Instead of managing one giant schema in a monolithic server, you can split your API into independently owned, deployable services — while still giving clients a single, cohesive endpoint to query.

At the center of federation is the supergraph: a composed schema that combines all subgraphs into one API.

TL;DR Federation lets you scale your GraphQL APIs across teams, domains, and services without sacrificing a great client experience.

Building large-scale GraphQL APIs brings common challenges:

• Monolithic schemas become hard to manage and deploy.
• Tight coupling between teams slows down development.
• Conflicting ownership over parts of the schema causes friction.
• Scaling a single server to handle all requests becomes a bottleneck.

Federation solves these by enabling:

• Decentralized development: each team owns and deploys their own schema.
• Unified experience: clients still query a single endpoint.
• Scalability: independently scaling subgraphs based on demand.

It’s the natural evolution for growing GraphQL architectures; especially when microservices or domain-driven design (DDD) principles are involved.

Let's break down the core components:

Each subgraph is a GraphQL service that defines a portion of the overall schema.

Subgraphs can extend types from other services, declare ownership over fields, and resolve parts of the data.

Example:

products subgraph:

type Product @key(fields: "id") {
  id: ID!
  name: String!
  brand: String!
  size: Float!
  color: String!
  price: Float!
}

type Query {
  product(id: ID!): Product
  products: [Product]
}

orders subgraph:

type Order @key(fields: "id") {
  id: ID!
  customerName: String!
  items: [OrderItem!]!
  total: Float!
}

type OrderItem {
  product: Product!
  quantity: Int!
}

type Product @key(fields: "id") {
  id: ID!
}

type Query {
  order(id: ID!): Order
  orders: [Order]
}

The supergraph is the composition of all subgraphs into one executable schema. Clients query the supergraph without knowing how the API is distributed behind the scenes.

The gateway (or hosting platform like Grafbase) handles:

• Exposing the merged schema
• Determining which subgraphs can resolve which parts of the query
• Making a plan on how to query data from the subgraphs taking into account data dependencies

Federation introduces special directives, such as:

• @key: Defines the primary identifier for a type that identifies items across different subgraphs
• @requires: Declaratively request that the gateway injects data from other subgraphs into a resolver
• @overrides: Declare that one subgraph takes over resolving a specific field from another subgraph

These directives tell the gateway how different parts of the graph connect.

Schema Stitching was an earlier method to combine multiple GraphQL schemas.

While useful, stitching requires complex manual work to resolve types and often doesn’t scale cleanly.

Federation is purpose-built for modular GraphQL APIs, making it scalable, maintainable, and team-friendly.

Setting up federation traditionally required running your own gateway, managing routing, and deploying multiple services manually.

And Grafbase simplifies all of this.

With Grafbase Federation:

• Subgraphs can be deployed instantly.
• Composition is handled automatically. You get a single endpoint, without maintaining infrastructure.
• Built-in caching, authentication, and performance optimizations.

Deploying a federated supergraph with Grafbase often takes just a few minutes, making it ideal for modern teams moving fast.

Here's an example inventory subgraph extending the subgraphs defined above:

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.6", import: ["@key"])

type Product @key(fields: "id") {
  id: ID!
  stock: Int
  location: String
}

Once published, Grafbase automatically composes and updates your supergraph.

• Take advantage of the security measures in the Grafbase Gateway (authentication, authorization, rate limiting, complexity analysis, CSRF protection, ...)
• Secure the communication between gateway and subgraphs (authentication headers, TLS, ...)
• Monitor and optimize: use the Grafbase built-in observability and analytics tooling (based on OpenTelemetry) to understand, troubleshoot and optimize your API.

GraphQL Federation unlocks the power of modular APIs without sacrificing the simplicity clients expect.

It enables scaling GraphQL across organizations and with platforms like Grafbase, it's easier than ever to adopt.

Ready to start federating your GraphQL services?

Check out our introduction to GraphQL Federation or get in touch with our team!