You're viewing documentation for a version of this software that is in development. Switch to the latest stable version
Launch Apollo Studio

Apollo Federation 2 alpha

Combine APIs into a unified graph


📣 Apollo Federation 2 is in public alpha.

Unchanged portions of the federation docs are omitted for clarity. These portions are available in the Federation 1 docs.

Apollo Federation is a powerful open-source architecture that helps you create a unified graph that combines multiple GraphQL APIs:

Supergraph
gateway
Users
subgraph
Products
subgraph
Reviews
subgraph

With federation, you can responsibly share ownership of your graph across any number of teams. 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.

Federation also supports a free managed mode with Apollo Studio, which helps you modify and grow your graph 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 supergraph, clients can query all of your subgraphs at the same time:

Supergraph
gateway
Users
subgraph
Products
subgraph
Reviews
subgraph
Clients

A gateway serves as the public access point for your supergraph. It receives incoming GraphQL operations and intelligently distributes them across your subgraphs. To clients, this looks exactly the same as querying any other GraphQL server—no special configuration is required.

Apollo Federation does not currently support GraphQL subscription operations.

Combining subgraph schemas

Every subgraph has its own schema (just like any other GraphQL API):

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

To communicate with all of your subgraphs, the gateway uses a special supergraph schema that combines these subgraph schemas.

To create a supergraph schema, Apollo Federation uses a special process called composition. Composition takes all of your subgraph schemas and intelligently combines them into one schema for your gateway:

# Supergraph schema (simplified)
type User {
  id: ID!
  name: String!
}

type Product {
  upc: String!
  inStock: Boolean!
}

A real supergraph schema includes additional information that tells your gateway which subgraph is responsible for which types and fields. Learn more about composition.

Server instances

In a federated architecture, each subgraph instance has its own GraphQL server, and so does the gateway. External clients query the gateway, and the gateway then queries individual subgraphs to obtain and return results:

Gateway
Users
subgraph
Products
subgraph
Reviews
subgraph
Clients

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 REST.

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

✅

Gateway
Users
subgraph
Products
subgraph
Clients

By unifying your graph with Apollo Federation, teams can continue to own and develop their subgraphs independently, and clients can fetch data from all of those subgraphs 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
GraphQL server

By federating your graph, you can reduce performance and productivity bottlenecks simultaneously. Each team can maintain their own subgraph(s) independently, and your graph's gateway serves primarily to route incoming operations, 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
Gateway
Graph
team

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

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 subgraphs, it might seem straightforward that each subgraph would own a completely distinct set of types. For example, a Users subgraph would define the entirety of a User type, the Products subgraph would define a Product type, and so on:

❌

# Users subgraph
type User {
  name: String
  reviews: [Review]
  purchases: [Product]
}
# Products subgraph
type Product {
  name: String
  price: String
  reviews: [Review]
}
# Reviews subgraph
type Review {
  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 subgraphs.

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

By defining the User.purchases field in the Products subgraph instead:

  • The subgraph that defines the field 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 subgraph that they are responsible for.

Concern-based separation

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

✅

# Users subgraph
type User {
  name: String
}
# Products subgraph
type Product {
  name: String
  price: String
  reviews: [Review]
}

type User {
  purchases: [Product]
}
# Reviews subgraph
type Review {
  body: String
  author: User
  product: Product
}

type User {
  reviews: [Review]
}

type Product {
  reviews: [Review]
}

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

The result provides the best of both worlds:

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

Managed federation

A federated gateway can operate in managed federation mode, where Apollo Studio acts as the source of truth for your supergraph's configuration:

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

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


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

Edit on GitHub