Skip to content

Commit 9873ee9

Browse files
kamilkisielabenjieandrewicarlson
authored
Learn GraphQL federation (#1826)
* Learn GraphQL federation * prettier * fix * I can do this all day long... * told you... * Update src/pages/learn/federation.mdx * Thank you @andrewicarlson Co-authored-by: Andrew Carlson <[email protected]> * Apply feedback * Apply Benjie's feedback * Make it clear you do not need federation on day 1 * Apply suggestions - intro --------- Co-authored-by: Benjie <[email protected]> Co-authored-by: Andrew Carlson <[email protected]>
1 parent 4c8343e commit 9873ee9

File tree

2 files changed

+272
-0
lines changed

2 files changed

+272
-0
lines changed

‎src/pages/learn/_meta.ts

+1
Original file line numberDiff line numberDiff line change
@@ -26,4 +26,5 @@ export default {
2626
caching: "",
2727
performance: "",
2828
security: "",
29+
federation: "",
2930
}

‎src/pages/learn/federation.mdx

+271
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
---
2+
sidebarTitle: Federation
3+
---
4+
5+
import { Tabs } from 'nextra/components'
6+
7+
# GraphQL federation
8+
9+
An alternative design approach to the classical monolith, often described as microservices, emphasizes breaking down complex systems into smaller, independently managed components. In some ways, GraphQL federation is like microservices for GraphQL - an architectural pattern that has found particular resonance in the GraphQL ecosystem.
10+
11+
GraphQL federation gained widespread adoption after
12+
[Apollo GraphQL introduced Apollo Federation in 2019](https://www.apollographql.com/blog/apollo-federation-f260cf525d21).
13+
Their implementation has become a reference point for the GraphQL community, helping establish
14+
federation as a standard architectural pattern for building a distributed graph in the GraphQL
15+
ecosystem.
16+
17+
With more companies and developers seeing the benefits of building a distributed GraphQL schema with
18+
federation, the GraphQL ecosystem is now moving towards standardization of federation patterns. The
19+
GraphQL Foundation's
20+
[Composite Schema Working Group](https://github.com/graphql/composite-schemas-wg), which includes
21+
engineers from various organizations across the industry including
22+
[Apollo GraphQL](https://apollographql.com), [ChilliCream](https://chillicream.com/),
23+
[Graphile](https://www.graphile.org/), [Hasura](https://hasura.io/),
24+
[Netflix](https://www.netflix.com/) and [The Guild](https://the-guild.dev), is actively working on
25+
creating
26+
[an official specification for GraphQL Federation](https://github.com/graphql/composite-schemas-spec).
27+
This effort aims to standardize how GraphQL services can be composed and executed across distributed
28+
systems, while ensuring room for innovation and different implementations.
29+
30+
## What is federation?
31+
32+
Architecturally, federation is an approach to organizing and managing distributed systems. At its
33+
core, federation allows autonomous components to work together while maintaining their independence.
34+
Think of it like a federal government system: individual states maintain their sovereignty while
35+
cooperating under a central authority for shared concerns.
36+
37+
In software architecture, federation enables organizations to:
38+
39+
- Distribute responsibility across independent teams
40+
- Scale different components independently
41+
- Maintain clear boundaries between different domains
42+
- Enable autonomous development and deployment
43+
- Reduce single points of failure
44+
45+
Think of the "Login with Google" or "Login with Facebook" buttons you see on websites. This is
46+
federation in action: you can use your Google or Facebook account to log into many different
47+
websites, even though each company manages their own login system separately.
48+
49+
## What is federated GraphQL?
50+
51+
GraphQL federation applies those principles to GraphQL APIs. It enables organizations to build a
52+
unified GraphQL schema from multiple independent services (most often called subgraphs), each
53+
responsible for its portion of the application's data graph.
54+
55+
Consider an e-commerce platform: You might have separate teams managing products, user accounts, and
56+
order processing. With GraphQL federation, each team can:
57+
58+
- Define their own GraphQL schema
59+
- Deploy and scale their service independently
60+
- Contribute to a unified GraphQL API without tight coupling
61+
- Maintain ownership of their domain-specific logic
62+
63+
The magic happens through a federated gateway that acts as the central coordinator, composing these
64+
separate schemas into a unified schema that clients can query.
65+
66+
## How federation works in GraphQL
67+
68+
The federation process involves several key components:
69+
70+
- **Subgraphs**: Individual services that define their own GraphQL schemas and resolvers
71+
- **Gateway**: A specialized service that sits between clients and your federated services
72+
- **Schema composition**: The process of merging schemas while resolving references between them,
73+
often handled by schema registries.
74+
75+
<Tabs items={['Products subgraph', 'Orders subgraph', 'Users subgraph']}> <Tabs.Tab>
76+
77+
```graphql
78+
type Product @key(fields: "id") {
79+
id: ID!
80+
title: String!
81+
price: Float!
82+
inStock: Boolean!
83+
}
84+
```
85+
86+
</Tabs.Tab> <Tabs.Tab>
87+
88+
```graphql
89+
type Order @key(fields: "id") {
90+
id: ID!
91+
products: [Product!]!
92+
total: Float!
93+
}
94+
95+
type Product {
96+
id: ID!
97+
}
98+
```
99+
100+
</Tabs.Tab> <Tabs.Tab>
101+
102+
```graphql
103+
type Query {
104+
user(id: ID!): User
105+
}
106+
107+
type User {
108+
id: ID!
109+
name: String!
110+
email: String
111+
orders: [Order!]!
112+
}
113+
114+
type Order {
115+
id: ID!
116+
}
117+
```
118+
119+
</Tabs.Tab> </Tabs>
120+
121+
### Schema composition
122+
123+
Let's break down schema composition in GraphQL federation with more detail and examples. Schema
124+
composition is the process where multiple subgraph schemas are combined into one unified schema.
125+
It's more complex than simply merging schemas together, though, because it needs to handle
126+
relationships, detect incompatibilities, and ensure types are properly connected across services and
127+
subgraphs.
128+
129+
Based on the examples we provided before, here's the unified schema GraphQL clients will see and can
130+
query:
131+
132+
```graphql
133+
type Query {
134+
user(id: ID!): User
135+
}
136+
137+
type User {
138+
id: ID!
139+
name: String!
140+
email: String
141+
orders: [Order!]!
142+
}
143+
144+
type Order {
145+
id: ID!
146+
products: [Product!]!
147+
total: Float!
148+
}
149+
150+
type Product {
151+
id: ID!
152+
title: String!
153+
price: Float!
154+
inStock: Boolean!
155+
}
156+
```
157+
158+
This unified schema combines types and fields from all three subgraphs (Users, Orders, and
159+
Products), allowing clients to seamlessly query across these domains.
160+
161+
### Gateway
162+
163+
The federation gateway is the entry point to your distributed data graph. It presents a unified
164+
GraphQL endpoint to clients and handles the complexity of routing queries to the appropriate
165+
subgraphs and assembling the results, and often provides caching and performance optimizations.
166+
167+
```mermaid
168+
graph TD
169+
Client --> FederationGateway
170+
FederationGateway --> UsersService
171+
FederationGateway --> OrdersService
172+
FederationGateway --> ProductsService
173+
174+
Client[Client]
175+
FederationGateway[Gateway]
176+
UsersService[Users Service]
177+
OrdersService[Orders Service]
178+
ProductsService[Products Service]
179+
```
180+
181+
Take the following query as an example:
182+
183+
```graphql
184+
query {
185+
user(id: "123") {
186+
# Resolved by Users subgraph
187+
name
188+
orders {
189+
# Resolved by Orders subgraph
190+
id
191+
products {
192+
# Resolved by Products subgraph
193+
title
194+
price
195+
}
196+
}
197+
}
198+
}
199+
```
200+
201+
The gateway will route parts of the query to the appropriate subgraphs, collect the results, and
202+
assemble them into a single response that the client can consume.
203+
204+
## Benefits of GraphQL federation
205+
206+
### Domain-driven development
207+
208+
Teams can work independently on their services while contributing to a cohesive API. This autonomy
209+
accelerates development and reduces coordination overhead.
210+
211+
### Service integrity protection
212+
213+
The schema composition step verifies integration between services by ensuring that changes in
214+
individual subgraphs do not conflict with other subgraphs.
215+
216+
### Scalability and performance
217+
218+
Subgraphs and services can be scaled independently based on their specific requirements. The product
219+
catalog might need different scaling characteristics than the order processing system.
220+
221+
### Single, unified API
222+
223+
Thanks to GraphQL, clients get a single endpoint with unified schema spanning multiple subgraphs.
224+
The complexity of distributed systems is hidden. The gateway ensures every query reaches its
225+
destination and returns with the right data.
226+
227+
## Is GraphQL federation right for you?
228+
229+
GraphQL federation aligns naturally with Domain Driven Design (DDD) principles by allowing teams to
230+
maintain clear boundaries around their domains, while maintaining explicit integration points
231+
through the GraphQL schema. It is particularly valuable for organizations where multiple teams need
232+
to work independently on different parts of the GraphQL API, with the flexibility to use different
233+
technologies and programming languages.
234+
235+
However, implementing federation requires substantial infrastructure support, including a dedicated
236+
team to manage the gateway, schema registry, to help connect subgraphs to the federated API and
237+
guide teams on best practices.
238+
239+
Before adopting federation, it's crucial to consider whether your organization truly needs this
240+
level of complexity. You can start with a monolithic setup and transition to federation as your needs
241+
evolve, rather than implementing it prematurely.
242+
243+
Meta (formerly Facebook), [where GraphQL was created](/blog/2015-09-14-graphql/), has continued to
244+
use a monolithic GraphQL API since 2012. However, companies like
245+
[Netflix](https://netflixtechblog.com/how-netflix-scales-its-api-with-graphql-federation-part-1-ae3557c187e2),
246+
[Expedia Group](https://youtu.be/kpeVT7J6Bsw?si=srGWsoxf3kTmneTu&t=79),
247+
[Volvo](https://www.apollographql.com/blog/volvo-cars-drives-into-the-future-of-online-car-shopping-with-the-supergraph),
248+
and [Booking](https://youtu.be/2KsP_x50tGk?si=mu-MOG-xZQSDNDjh&t=478) have adopted federation to
249+
better align with their organizational structures and microservices architecture.
250+
251+
As you see, some of the world's largest industry leaders have successfully federated their GraphQL
252+
APIs, proving that it works reliably for production applications at an extraordinary scale.
253+
254+
## Getting started with GraphQL federation
255+
256+
If you're considering adopting GraphQL federation, here are some steps to get started:
257+
258+
1. **Identify Service Boundaries**: Define clear boundaries between different domains in your
259+
application
260+
2. [**Design Schemas**](/learn/schema/ 'Learn about the different elements of the GraphQL type system'):
261+
Create schemas that reflect these boundaries while considering how they'll interact
262+
3. [**Implement Subgraphs**](/community/tools-and-libraries/?tags=server 'Discover a list of GraphQL servers in our Tools and Libraries page'):
263+
Build individual services that implement their portion of the schema
264+
4. [**Set Up a Gateway**](/community/tools-and-libraries/?tags=gateways-supergraphs 'Discover a list of GraphQL gateways in our Tools and Libraries page'):
265+
Deploy a federation gateway to compose and serve the unified schema
266+
5. [**Use a Schema Registry**](/community/tools-and-libraries/?tags=schema-registry 'Discover a list of GraphQL schema registries in our Tools and Libraries page'):
267+
Manage schema composition and validation to ensure integrity across subgraphs
268+
269+
When migrating from a monolithic to federated GraphQL API, the simplest starting point is to treat
270+
your existing schema as your first subgraph. From there, you can follow the steps above to gradually
271+
decompose your schema into smaller pieces.

0 commit comments

Comments
 (0)