Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Docs
Launch GraphOS Studio

Introduction to Apollo Federation

Combine GraphQL APIs into a unified supergraph


Apollo Federation is a powerful, open architecture for creating a supergraph that combines multiple GraphQL APIs:

Supergraph
Router
Users
subgraph
Products
subgraph
Clients

With federation, you can responsibly share ownership of your across any number of teams and services. And even if you currently only have one GraphQL API, Apollo Federation is essential for scaling that API as you grow your features, user base, and organization.

Apollo GraphOS provides a managed mode for Apollo Federation, which helps you modify and grow your without any downtime.

Get started with FederationLearn more

How it works

In a federated architecture, your individual GraphQL APIs are called subgraphs, and they're composed into a supergraph. By querying your 's , clients can fetch data from all of your s with a single request:

Supergraph
Router
Users
subgraph
Products
subgraph
Clients

The router serves as the public access point for your . It receives incoming GraphQL s and intelligently routes them across your s. To clients, this looks exactly the same as querying any other GraphQL server—no client-side configuration is required.

Combining subgraph schemas

Like any other GraphQL API, each has its own :

Users subgraph
type User {
id: ID!
name: String!
}
Products subgraph
type Product {
upc: String!
inStock: Boolean!
}

To communicate with all of your s, the uses a special supergraph schema that combines these s.

s are created via a process called composition. Composition takes all of your s and intelligently combines them into one for your :

Supergraph schema (simplified)
type User {
id: ID!
name: String!
}
type Product {
upc: String!
inStock: Boolean!
}

A real includes additional information that tells your which is responsible for which types and s. Learn more about composition.

Server instances

In a federated architecture, each instance is a GraphQL service that's queried only by the . The router is a separate service that exposes a GraphQL endpoint to external clients. Clients query the router, and the router then queries individual s to obtain, combine, and return results:

Supergraph
Router
Users
subgraph
Products
subgraph
Clients

The router is one of the following:

Subgraphs can each use any subgraph-compatible GraphQL server library.

  • This includes Apollo Server using special extensions from the @apollo/subgraph library.
  • Different s in the same can use different server libraries.

Benefits of federation

Unify your graph

Often when an organization first adopts GraphQL, multiple teams do so independently. Each team sets up a GraphQL server that provides the data used by that team:

Product
data
Products API
User
data
Users API
Clients

But with an architecture like this, a client might need to communicate with multiple APIs to fetch all of the data it needs. This diminishes a powerful advantage of GraphQL over traditional REST APIs.

Instead, your organization should expose a unified supergraph that lets clients fetch all of the data that they need from a single endpoint:

Supergraph
Router
Users
subgraph
Products
subgraph
Clients

By unifying your with Apollo Federation, teams can continue to own and develop their s independently, and clients can fetch data from all of those s with a single query.

Break up monolithic code

It can be challenging to represent an entire enterprise-scale graph with a monolithic GraphQL server. Performance might degrade as your users and features increase, and teams across your organization are all committing changes to the same application:

Users
team
Flights
team
Hotels
team
Billing
team
Bookings
team
Monolith
GraphQL server

With a , you can reduce performance and productivity bottlenecks simultaneously. Each team can maintain their own (s) independently, and your 's serves primarily to route incoming s, not to resolve each of them completely.

Users
team
Flights
team
Hotels
team
Billing
team
Bookings
team
Users
subgraph
Flights
subgraph
Hotels
subgraph
Billing
subgraph
Bookings
subgraph
Router
Graph
team

In this structure, the "graph team" might be a separate team that's dedicated to maintaining your as part of back-end infrastructure, or it might be a "meta team" that includes representatives from other teams that maintain s.

Adopt incrementally

As with the rest of the Apollo platform, you can (and should) adopt Apollo Federation incrementally:

In both of these cases, all of your clients continue to work throughout your incremental adoption. In fact, clients have no way to distinguish between different graph implementations.

Separation of concerns

Apollo Federation encourages a design principle called separation of concerns. This enables different teams to work on different products and features within a single graph, without interfering with each other.

Limitations of type-based separation

When thinking about how to divide your graph's functionality across s, it might initially seem logical for each subgraph to own a completely distinct set of types. For example, a Users subgraph would define the entirety of a User type, the Products would define a Product type, and so on:

Users subgraph
type User {
id: ID!
name: String
reviews: [Review]
purchases: [Product]
}
Products subgraph
type Product {
id: ID!
name: String
price: String
reviews: [Review]
}
Reviews subgraph
type Review {
id: ID!
body: String
author: User
product: Product
}

Although this separation looks clean, it quickly causes issues. Most commonly, a particular feature (or concern) usually spans multiple types, which might belong to different s.

Consider the User.purchases above. Even though this field belongs to the User type, a list of Products should probably be populated by the Products , not the Users .

By defining the User.purchases in the Products instead:

  • The that defines the is also the subgraph that knows how to populate the field. The Users subgraph might not even have access to the back-end data store that contains product data!
  • The team that manages product data can contain all product-related logic in a single that they are responsible for.

Concern-based separation

The following uses Apollo Federation to divide the same set of types and s across the same three s:

Some federation-specific syntax is omitted here for clarity. For details, see Entities.

Users subgraph
type User {
id: ID!
name: String
}
Products subgraph
type Product {
id: ID!
name: String
price: String
}
type User {
id: ID!
purchases: [Product]
}
Reviews subgraph
type Review {
id: ID!
body: String
author: User
product: Product
}
type User {
id: ID!
reviews: [Review]
}
type Product {
id: ID!
reviews: [Review]
}

The difference is that now, each mostly defines types and s that it is capable of (and should be responsible for) populating from its back-end data store.

You'll notice some exceptions to this, such as Review.product (which is still defined in the Reviews even though it requires data from the Products subgraph). Exceptions like this improve data encapsulation (the Products subgraph doesn't really need to know about the Review type), and we handle them with powerful federated types called entities.

These resulting s provide the best of both worlds:

  • An implementation that keeps the code for a given feature in a single and separated from unrelated concerns
  • A product-centric with rich types that reflect the natural way an application developer wants to consume the graph

Managed federation

Your can operate in managed federation mode, where Apollo GraphOS acts as the source of truth for your 's configuration:

Apollo GraphOS
Your infrastructure
Publishes
schema
Publishes
schema
Updates
supergraph config
Polls for supergraph changes
Apollo Schema
Registry
Apollo
Uplink
Products
subgraph
Reviews
subgraph
Router

This mode helps multiple teams working on a to coordinate when and how to change individual s. It's recommended for all supergraphs. For more information, read Managed federation overview.


Ready to try out Apollo Federation? Jump into the Quickstart!

Next
Changelog
Edit on GitHubEditForumsDiscord