Introduction
As organizations adopt microservices architectures, managing APIs becomes increasingly challenging. Each microservice typically exposes its own API, resulting in multiple endpoints, inconsistent data access patterns, and increased complexity for frontend applications.
GraphQL helps solve some of these challenges by providing a flexible query language that allows clients to request exactly the data they need. However, as the number of microservices grows, maintaining a single GraphQL server can become difficult.
This is where GraphQL Federation comes in.
GraphQL Federation allows multiple GraphQL services to work together as a single unified API. Each team can independently own and develop its portion of the schema while clients interact with a single GraphQL endpoint.
In this article, you'll learn what GraphQL Federation is, how it works, its architecture, and how to implement it using practical microservices examples.
What Is GraphQL Federation?
GraphQL Federation is an architecture pattern that combines multiple GraphQL services into a single federated schema.
Instead of creating one large GraphQL server that contains all business logic, each microservice manages its own schema and functionality.
A federation gateway then combines these services into a unified API.
Without Federation:
Frontend
│
├── User Service API
├── Product Service API
├── Order Service API
└── Inventory Service API
With Federation:
Frontend
│
▼
Federation Gateway
│
├── User Service
├── Product Service
├── Order Service
└── Inventory Service
The frontend interacts with only one endpoint while the gateway coordinates requests behind the scenes.
Why Traditional GraphQL Architectures Become Challenging
In small applications, a single GraphQL server works well.
However, large systems often face challenges such as:
Large monolithic schemas
Team ownership conflicts
Slow deployment cycles
Difficult scalability
Tight service coupling
Complex codebases
As organizations grow, multiple teams need to work independently without affecting each other's APIs.
Federation enables decentralized API ownership while maintaining a unified developer experience.
Understanding GraphQL Federation Architecture
A federated GraphQL architecture typically consists of three components.
Subgraphs
Each microservice exposes its own GraphQL schema.
Examples:
User Service
Product Service
Order Service
Inventory Service
Federation Gateway
The gateway combines schemas into a single graph.
Responsibilities include:
Query planning
Schema composition
Request routing
Response aggregation
Clients
Applications interact only with the gateway.
Architecture overview:
Client Application
│
▼
Federation Gateway
│
┌──────┼──────┐
▼ ▼ ▼
Users Products Orders
Service Service Service
This approach provides both flexibility and scalability.
Understanding Subgraphs
A subgraph represents a GraphQL service responsible for a specific business domain.
Example User Service schema:
type User @key(fields: "id") {
id: ID!
name: String!
email: String!
}
Example Product Service schema:
type Product @key(fields: "id") {
id: ID!
name: String!
price: Float!
}
Each service owns and manages its own data.
Understanding the @key Directive
The @key directive is one of the most important concepts in GraphQL Federation.
Example:
type User @key(fields: "id") {
id: ID!
name: String!
}
The key identifies an entity across services.
This allows multiple subgraphs to reference the same object without duplicating data.
Building a User Service
Let's create a simple User Service.
Schema:
type User @key(fields: "id") {
id: ID!
name: String!
}
type Query {
user(id: ID!): User
}
Resolver:
const resolvers = {
Query: {
user(_, { id }) {
return {
id,
name: "John Doe"
};
}
}
};
This service owns user-related data.
Building an Order Service
The Order Service manages customer orders.
Schema:
type Order {
id: ID!
amount: Float!
user: User!
}
extend type User @key(fields: "id") {
id: ID! @external
}
Notice that the User entity is referenced rather than duplicated.
Resolver:
const resolvers = {
Order: {
user(order) {
return {
id: order.userId
};
}
}
};
This establishes relationships between services.
Schema Composition
The Federation Gateway combines multiple schemas automatically.
Combined schema:
type User {
id: ID!
name: String!
}
type Order {
id: ID!
amount: Float!
user: User!
}
Join the conversation! Your thoughts help the community grow.