From 9ccaeb5e01ee18d0e7dddc930626040cfa17743a Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Fri, 15 Nov 2024 11:27:50 +0100 Subject: [PATCH 01/11] Learn GraphQL federation --- src/pages/learn/_meta.ts | 1 + src/pages/learn/federation.mdx | 249 +++++++++++++++++++++++++++++++++ 2 files changed, 250 insertions(+) create mode 100644 src/pages/learn/federation.mdx diff --git a/src/pages/learn/_meta.ts b/src/pages/learn/_meta.ts index 4affaab60a..bdb83c1c98 100644 --- a/src/pages/learn/_meta.ts +++ b/src/pages/learn/_meta.ts @@ -20,4 +20,5 @@ export default { pagination: "", "global-object-identification": "", caching: "", + "federation": "", } diff --git a/src/pages/learn/federation.mdx b/src/pages/learn/federation.mdx new file mode 100644 index 0000000000..bab8d12504 --- /dev/null +++ b/src/pages/learn/federation.mdx @@ -0,0 +1,249 @@ +--- +sidebarTitle: Federation +--- + +import { Tabs } from 'nextra/components' + +# GraphQL Federation + +In today's world of distributed systems and microservices, +organizations face the challenge of efficiently managing and scaling their APIs. +As applications grow more complex, traditional monolithic approaches often fall short. +This is where federation comes into play - an architectural pattern that has found particular resonance in the GraphQL ecosystem. + +GraphQL Federation gained widespread adoption after [Apollo GraphQL introduced Apollo Federation in 2019](https://www.apollographql.com/blog/apollo-federation-f260cf525d21). +Their implementation has become a reference point for the GraphQL community, +helping establish federation as a standard architectural pattern in the GraphQL ecosystem. + +The GraphQL ecosystem is moving towards standardization of federation patterns. +The GraphQL Foundation's [Composite Schema Working Group](https://github.com/graphql/composite-schemas-wg), +which includes engineers from various organizations across the industry including +Apollo GraphQL, ChilliCream, Google, Graphile, The Guild, Hasura, and IBM, +is actively working on creating an official specification for GraphQL Federation. +This effort aims to standardize how GraphQL services can be composed and executed across distributed systems, +while ensuring room for innovation and different implementations. + +## What is federation? + +Federation is an approach to organizing and managing distributed systems. +At its core, federation allows autonomous components to work together while maintaining their independence. +Think of it like a federal government system: individual states maintain their sovereignty +while cooperating under a central authority for shared concerns. + +In software architecture, federation enables organizations to: + +- Distribute responsibility across independent teams +- Scale different components independently +- Maintain clear boundaries between different domains +- Enable autonomous development and deployment +- Reduce single points of failure + +Think of the "Login with Google" or "Login with Facebook" buttons you see on websites. +This is federation in action: you can use your Google or Facebook account to log into many different websites, +even though each company manages their own login system separately. + +## What Is Federated GraphQL? + +GraphQL Federation applies those principles to GraphQL APIs. +It enables organizations to build a unified GraphQL schema from multiple independent services (most often called subgraphs), +each responsible for its portion of the application's data graph. + +Consider an e-commerce platform: You might have separate teams managing products, user accounts, and order processing. With GraphQL Federation, each team can: + +- Define their own GraphQL schema +- Deploy and scale their service independently +- Contribute to a unified API without tight coupling +- Maintain ownership of their domain-specific logic + +The magic happens through a federated gateway that acts as the central coordinator, combining these separate schemas into a unified schema that clients can query. + +## How Federation Works in GraphQL + +The federation process involves several key components: + +- **Subgraphs**: Individual services that define their own GraphQL schemas and resolvers +- **Gateway**: A specialized service that sits between clients and your federated services +- **Schema composition**: The process of merging schemas while resolving references between them, often handled by schema registries. + + + +`graphql + type Product @key(fields: "id") { + id: ID! + title: String! + price: Float! + inStock: Boolean! + } + ` + + +```graphql +type Order @key(fields: "id") { +id: ID! +products: [Product!]! +total: Float! +} + + type Product { + id: ID! + } + ``` + + + +```graphql +type Query { +user(id: ID!): User +} + + type User { + id: ID! + name: String! + email: String + orders: [Order!]! + } + + type Order { + id: ID! + } + ``` + + + + +### Schema Composition + +Let's break down schema composition in GraphQL federation with more detail and examples. +Schema composition is the process where multiple subgraph schemas are combined into one unified schema. +It's more complex than simply merging schemas together, because it needs to handle relationships, detect incompatibilities, and ensure types are properly connected across services. + +Based on the examples we provided before, here's the unified schema GraphQL clients will see and can query: + +```graphql +type Query { + user(id: ID!): User +} + +type User { + id: ID! + name: String! + email: String + orders: [Order!]! +} + +type Order { + id: ID! + products: [Product!]! + total: Float! +} + +type Product { + id: ID! + title: String! + price: Float! + inStock: Boolean! +} +``` + +This unified schema combines types and fields from all three subgraphs (Users, Orders, and Products), allowing clients to seamlessly query across these domains. + +### Gateway + +The federation gateway is the entry point to your distributed data graph. +It presents a unified GraphQL endpoint to clients +and handles the complexity of routing queries to the appropriate subgraphs and assembling the results, +often provides caching and performance optimizations. + +```mermaid +graph TD + Client --> FederationGateway + FederationGateway --> UserService + FederationGateway --> OrderService + FederationGateway --> ProductService + + Client[Client] + FederationGateway[Gateway] + UserService[User Service] + OrderService[Order Service] + ProductService[Product Service] +``` + +Take the following query as an example: + +```graphql +query { + user(id: "123") { + # Resolved by Users subgraph + name + orders { + # Resolved by Orders subgraph + id + products { + # Resolved by Products subgraph + title + price + } + } + } +} +``` + +The gateway will route parts of the query to the appropriate subgraphs, collect the results, +and assemble them into a single response that the client can consume. + +## Benefits of GraphQL Federation + +### Domain-Driven Development + +Teams can work independently on their services while contributing to a cohesive API. +This autonomy accelerates development and reduces coordination overhead. + +### Service Integrity Protection + +The schema composition step verifies integration between services +by ensuring that changes in individual subgraphs +do not conflict with other subgraphs in the federation. + +### Scalability and Performance + +Services can be scaled independently based on their specific requirements. +The product catalog might need different scaling characteristics than the order processing system. + +### Single, Unified API + +Thanks to GraphQL gateway, clients get a single endpoint with unified schema. +The complexity of distributed systems is hidden. +The gateway ensures every query reaches its destination and returns with the right data. + +## Federation vs. Monolithic Architecture + +While monolithic GraphQL APIs have their place, federation offers several advantages for larger applications: + +| **Aspect** | **Monolithic GraphQL** | **Federated GraphQL** | +| ----------------- | --------------------------------- | ----------------------------- | +| Development Speed | Initially faster | Better for long-term velocity | +| Team Coordination | Requires significant coordination | Enables independence | +| Deployment | All-or-nothing | Independent deployments | +| Scaling | Entire system scales together | Independent scaling | + +## Real-World Implementations + +GraphQL Federation is adopted by tech giants such as +[Netlifx](https://netflixtechblog.com/how-netflix-scales-its-api-with-graphql-federation-part-1-ae3557c187e2), +[Expedia Group](https://youtu.be/kpeVT7J6Bsw?si=srGWsoxf3kTmneTu&t=79), +[Volvo](https://www.apollographql.com/blog/volvo-cars-drives-into-the-future-of-online-car-shopping-with-the-supergraph), +and [Booking](https://youtu.be/2KsP_x50tGk?si=mu-MOG-xZQSDNDjh&t=478). + +Many industry leaders successfully use GraphQL federation at scale, proving that federation works reliably for large-scale production applications. + +## Getting Started with GraphQL Federation + +To implement GraphQL federation, organizations should: + +1. **Identify Service Boundaries**: Define clear boundaries between different domains in your application +2. **Design Schemas**: Create schemas that reflect these boundaries while considering how they'll interact +3. **Implement Subgraphs**: Build individual services that implement their portion of the schema +4. **Set Up Gateway**: Deploy a federation gateway to compose and serve the unified schema +5. **Monitor and Optimize**: Implement monitoring and continuously optimize query performance + +Organizations can gradually migrate from a monolithic to federated GraphQL, one service at a time. From 1793df410cd4b021ffb98c98cfa4bce21bc3195e Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Fri, 15 Nov 2024 11:32:40 +0100 Subject: [PATCH 02/11] prettier --- src/pages/learn/_meta.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/learn/_meta.ts b/src/pages/learn/_meta.ts index bdb83c1c98..c7d0fb24ae 100644 --- a/src/pages/learn/_meta.ts +++ b/src/pages/learn/_meta.ts @@ -20,5 +20,5 @@ export default { pagination: "", "global-object-identification": "", caching: "", - "federation": "", + federation: "", } From bd68e6303f18f57a6e4cce2dfa2beb26720e60f5 Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Fri, 15 Nov 2024 11:40:32 +0100 Subject: [PATCH 03/11] fix --- src/pages/learn/federation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/learn/federation.mdx b/src/pages/learn/federation.mdx index bab8d12504..9ec697ac44 100644 --- a/src/pages/learn/federation.mdx +++ b/src/pages/learn/federation.mdx @@ -67,7 +67,7 @@ The federation process involves several key components: -`graphql +```graphql type Product @key(fields: "id") { id: ID! title: String! From f0e12e587ec67b981e5ed8a3241baf10238a08a2 Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Fri, 15 Nov 2024 11:49:13 +0100 Subject: [PATCH 04/11] I can do this all day long... --- src/pages/learn/federation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/learn/federation.mdx b/src/pages/learn/federation.mdx index 9ec697ac44..9cb4a614ef 100644 --- a/src/pages/learn/federation.mdx +++ b/src/pages/learn/federation.mdx @@ -74,7 +74,7 @@ The federation process involves several key components: price: Float! inStock: Boolean! } - ` + ``` ```graphql From 3dd1d8d53914d99d10c1705ac53085448cb9f0f6 Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Fri, 15 Nov 2024 12:18:33 +0100 Subject: [PATCH 05/11] told you... --- src/pages/learn/federation.mdx | 73 ++++++++++++++++++---------------- 1 file changed, 38 insertions(+), 35 deletions(-) diff --git a/src/pages/learn/federation.mdx b/src/pages/learn/federation.mdx index 9cb4a614ef..b6947d419b 100644 --- a/src/pages/learn/federation.mdx +++ b/src/pages/learn/federation.mdx @@ -67,46 +67,49 @@ The federation process involves several key components: + ```graphql - type Product @key(fields: "id") { - id: ID! - title: String! - price: Float! - inStock: Boolean! - } - ``` +type Product @key(fields: "id") { + id: ID! + title: String! + price: Float! + inStock: Boolean! +} +``` + + ```graphql type Order @key(fields: "id") { -id: ID! -products: [Product!]! -total: Float! + id: ID! + products: [Product!]! + total: Float! } - type Product { - id: ID! - } - ``` +type Product { + id: ID! +} +``` ```graphql type Query { -user(id: ID!): User + user(id: ID!): User } - type User { - id: ID! - name: String! - email: String - orders: [Order!]! - } +type User { + id: ID! + name: String! + email: String + orders: [Order!]! +} - type Order { - id: ID! - } - ``` +type Order { + id: ID! +} +``` @@ -156,16 +159,16 @@ often provides caching and performance optimizations. ```mermaid graph TD - Client --> FederationGateway - FederationGateway --> UserService - FederationGateway --> OrderService - FederationGateway --> ProductService - - Client[Client] - FederationGateway[Gateway] - UserService[User Service] - OrderService[Order Service] - ProductService[Product Service] + Client --> FederationGateway + FederationGateway --> UsersService + FederationGateway --> OrdersService + FederationGateway --> ProductsService + + Client[Client] + FederationGateway[Gateway] + UsersService[Users Service] + OrdersService[Orders Service] + ProductsService[Products Service] ``` Take the following query as an example: From 766407040688a7e73296db32bd8b7e2c4f4c7142 Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Thu, 21 Nov 2024 12:57:51 +0100 Subject: [PATCH 06/11] Update src/pages/learn/federation.mdx --- src/pages/learn/federation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/learn/federation.mdx b/src/pages/learn/federation.mdx index b6947d419b..dc6d51fb74 100644 --- a/src/pages/learn/federation.mdx +++ b/src/pages/learn/federation.mdx @@ -18,7 +18,7 @@ helping establish federation as a standard architectural pattern in the GraphQL The GraphQL ecosystem is moving towards standardization of federation patterns. The GraphQL Foundation's [Composite Schema Working Group](https://github.com/graphql/composite-schemas-wg), which includes engineers from various organizations across the industry including -Apollo GraphQL, ChilliCream, Google, Graphile, The Guild, Hasura, and IBM, +Apollo GraphQL, ChilliCream, Graphile, Hasura, Netflix and The Guild, is actively working on creating an official specification for GraphQL Federation. This effort aims to standardize how GraphQL services can be composed and executed across distributed systems, while ensuring room for innovation and different implementations. From 26551714b8fa8708b24ccf0bcaab3f55ecd90b3d Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Wed, 4 Dec 2024 12:14:57 +0100 Subject: [PATCH 07/11] Thank you @andrewicarlson Co-authored-by: Andrew Carlson <5479270+andrewicarlson@users.noreply.github.com> --- src/pages/learn/federation.mdx | 31 ++++++++++++++----------------- 1 file changed, 14 insertions(+), 17 deletions(-) diff --git a/src/pages/learn/federation.mdx b/src/pages/learn/federation.mdx index dc6d51fb74..5a28878dda 100644 --- a/src/pages/learn/federation.mdx +++ b/src/pages/learn/federation.mdx @@ -6,16 +6,13 @@ import { Tabs } from 'nextra/components' # GraphQL Federation -In today's world of distributed systems and microservices, -organizations face the challenge of efficiently managing and scaling their APIs. -As applications grow more complex, traditional monolithic approaches often fall short. -This is where federation comes into play - an architectural pattern that has found particular resonance in the GraphQL ecosystem. +As applications grow more complex, traditional monolithic approaches often fall short. At scale, monolithic architectures can become cumbersome, brittle, and increasingly hard to test and validate. This has led to a rise in the adoption of new patterns like distributed systems and microservices. In some ways, GraphQL Federation is like microservices for GraphQL – an architectural pattern that has found particular resonance in the GraphQL ecosystem. GraphQL Federation gained widespread adoption after [Apollo GraphQL introduced Apollo Federation in 2019](https://www.apollographql.com/blog/apollo-federation-f260cf525d21). Their implementation has become a reference point for the GraphQL community, -helping establish federation as a standard architectural pattern in the GraphQL ecosystem. +helping establish federation as a standard architectural pattern for building a distributed graph in the GraphQL ecosystem. -The GraphQL ecosystem is moving towards standardization of federation patterns. +With more companies and developers seeing the benefits of building a distributed graph with federation, the GraphQL ecosystem is now moving towards standardization of federation patterns. The GraphQL Foundation's [Composite Schema Working Group](https://github.com/graphql/composite-schemas-wg), which includes engineers from various organizations across the industry including Apollo GraphQL, ChilliCream, Graphile, Hasura, Netflix and The Guild, @@ -25,7 +22,7 @@ while ensuring room for innovation and different implementations. ## What is federation? -Federation is an approach to organizing and managing distributed systems. +Architecturally, federation is an approach to organizing and managing distributed systems. At its core, federation allows autonomous components to work together while maintaining their independence. Think of it like a federal government system: individual states maintain their sovereignty while cooperating under a central authority for shared concerns. @@ -52,10 +49,10 @@ Consider an e-commerce platform: You might have separate teams managing products - Define their own GraphQL schema - Deploy and scale their service independently -- Contribute to a unified API without tight coupling +- Contribute to a unified GraphQL API without tight coupling - Maintain ownership of their domain-specific logic -The magic happens through a federated gateway that acts as the central coordinator, combining these separate schemas into a unified schema that clients can query. +The magic happens through a federated gateway that acts as the central coordinator, composing these separate schemas into a unified schema that clients can query. ## How Federation Works in GraphQL @@ -118,7 +115,7 @@ type Order { Let's break down schema composition in GraphQL federation with more detail and examples. Schema composition is the process where multiple subgraph schemas are combined into one unified schema. -It's more complex than simply merging schemas together, because it needs to handle relationships, detect incompatibilities, and ensure types are properly connected across services. +It's more complex than simply merging schemas together, though, because it needs to handle relationships, detect incompatibilities, and ensure types are properly connected across services and subgraphs. Based on the examples we provided before, here's the unified schema GraphQL clients will see and can query: @@ -155,7 +152,7 @@ This unified schema combines types and fields from all three subgraphs (Users, O The federation gateway is the entry point to your distributed data graph. It presents a unified GraphQL endpoint to clients and handles the complexity of routing queries to the appropriate subgraphs and assembling the results, -often provides caching and performance optimizations. +and often provides caching and performance optimizations. ```mermaid graph TD @@ -205,22 +202,22 @@ This autonomy accelerates development and reduces coordination overhead. The schema composition step verifies integration between services by ensuring that changes in individual subgraphs -do not conflict with other subgraphs in the federation. +do not conflict with other subgraphs. ### Scalability and Performance -Services can be scaled independently based on their specific requirements. +Subgraphs and services can be scaled independently based on their specific requirements. The product catalog might need different scaling characteristics than the order processing system. ### Single, Unified API -Thanks to GraphQL gateway, clients get a single endpoint with unified schema. +Thanks to GraphQL, clients get a single endpoint with unified schema spanning multiple subgraphs. The complexity of distributed systems is hidden. The gateway ensures every query reaches its destination and returns with the right data. ## Federation vs. Monolithic Architecture -While monolithic GraphQL APIs have their place, federation offers several advantages for larger applications: +While monolithic GraphQL APIs have their place, federated architectures offer several advantages for larger applications: | **Aspect** | **Monolithic GraphQL** | **Federated GraphQL** | | ----------------- | --------------------------------- | ----------------------------- | @@ -246,7 +243,7 @@ To implement GraphQL federation, organizations should: 1. **Identify Service Boundaries**: Define clear boundaries between different domains in your application 2. **Design Schemas**: Create schemas that reflect these boundaries while considering how they'll interact 3. **Implement Subgraphs**: Build individual services that implement their portion of the schema -4. **Set Up Gateway**: Deploy a federation gateway to compose and serve the unified schema +4. **Set Up a federated Gateway**: Deploy a federation gateway to compose and serve the unified schema 5. **Monitor and Optimize**: Implement monitoring and continuously optimize query performance -Organizations can gradually migrate from a monolithic to federated GraphQL, one service at a time. +Organizations can gradually migrate from a monolithic to federated GraphQL implementation, one service at a time. From c31a7aa151e202ccbaaef8de4660ed945afa4015 Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Wed, 4 Dec 2024 16:20:59 +0100 Subject: [PATCH 08/11] Apply feedback --- src/pages/learn/federation.mdx | 177 +++++++++++++++++++-------------- 1 file changed, 101 insertions(+), 76 deletions(-) diff --git a/src/pages/learn/federation.mdx b/src/pages/learn/federation.mdx index 5a28878dda..2891e733f3 100644 --- a/src/pages/learn/federation.mdx +++ b/src/pages/learn/federation.mdx @@ -6,26 +6,37 @@ import { Tabs } from 'nextra/components' # GraphQL Federation -As applications grow more complex, traditional monolithic approaches often fall short. At scale, monolithic architectures can become cumbersome, brittle, and increasingly hard to test and validate. This has led to a rise in the adoption of new patterns like distributed systems and microservices. In some ways, GraphQL Federation is like microservices for GraphQL – an architectural pattern that has found particular resonance in the GraphQL ecosystem. - -GraphQL Federation gained widespread adoption after [Apollo GraphQL introduced Apollo Federation in 2019](https://www.apollographql.com/blog/apollo-federation-f260cf525d21). -Their implementation has become a reference point for the GraphQL community, -helping establish federation as a standard architectural pattern for building a distributed graph in the GraphQL ecosystem. - -With more companies and developers seeing the benefits of building a distributed graph with federation, the GraphQL ecosystem is now moving towards standardization of federation patterns. -The GraphQL Foundation's [Composite Schema Working Group](https://github.com/graphql/composite-schemas-wg), -which includes engineers from various organizations across the industry including -Apollo GraphQL, ChilliCream, Graphile, Hasura, Netflix and The Guild, -is actively working on creating an official specification for GraphQL Federation. -This effort aims to standardize how GraphQL services can be composed and executed across distributed systems, -while ensuring room for innovation and different implementations. +As applications grow more complex, traditional monolithic approaches often fall short. At scale, +monolithic architectures can become cumbersome, brittle, and increasingly hard to test and validate. +This has led to a rise in the adoption of new patterns like distributed systems and microservices. +In some ways, GraphQL Federation is like microservices for GraphQL – an architectural pattern that +has found particular resonance in the GraphQL ecosystem. + +GraphQL Federation gained widespread adoption after +[Apollo GraphQL introduced Apollo Federation in 2019](https://www.apollographql.com/blog/apollo-federation-f260cf525d21). +Their implementation has become a reference point for the GraphQL community, helping establish +federation as a standard architectural pattern for building a distributed graph in the GraphQL +ecosystem. + +With more companies and developers seeing the benefits of building a distributed graph with +federation, the GraphQL ecosystem is now moving towards standardization of federation patterns. The +GraphQL Foundation's +[Composite Schema Working Group](https://github.com/graphql/composite-schemas-wg), which includes +engineers from various organizations across the industry including +[Apollo GraphQL](https://apollographql.com), [ChilliCream](https://chillicream.com/), +[Graphile](https://www.graphile.org/), [Hasura](https://hasura.io/), +[Netflix](https://www.netflix.com/) and [The Guild](https://the-guild.dev), is actively working on +creating +[an official specification for GraphQL Federation](https://github.com/graphql/composite-schemas-spec). +This effort aims to standardize how GraphQL services can be composed and executed across distributed +systems, while ensuring room for innovation and different implementations. ## What is federation? -Architecturally, federation is an approach to organizing and managing distributed systems. -At its core, federation allows autonomous components to work together while maintaining their independence. -Think of it like a federal government system: individual states maintain their sovereignty -while cooperating under a central authority for shared concerns. +Architecturally, federation is an approach to organizing and managing distributed systems. At its +core, federation allows autonomous components to work together while maintaining their independence. +Think of it like a federal government system: individual states maintain their sovereignty while +cooperating under a central authority for shared concerns. In software architecture, federation enables organizations to: @@ -35,24 +46,26 @@ In software architecture, federation enables organizations to: - Enable autonomous development and deployment - Reduce single points of failure -Think of the "Login with Google" or "Login with Facebook" buttons you see on websites. -This is federation in action: you can use your Google or Facebook account to log into many different websites, -even though each company manages their own login system separately. +Think of the "Login with Google" or "Login with Facebook" buttons you see on websites. This is +federation in action: you can use your Google or Facebook account to log into many different +websites, even though each company manages their own login system separately. ## What Is Federated GraphQL? -GraphQL Federation applies those principles to GraphQL APIs. -It enables organizations to build a unified GraphQL schema from multiple independent services (most often called subgraphs), -each responsible for its portion of the application's data graph. +GraphQL Federation applies those principles to GraphQL APIs. It enables organizations to build a +unified GraphQL schema from multiple independent services (most often called subgraphs), each +responsible for its portion of the application's data graph. -Consider an e-commerce platform: You might have separate teams managing products, user accounts, and order processing. With GraphQL Federation, each team can: +Consider an e-commerce platform: You might have separate teams managing products, user accounts, and +order processing. With GraphQL Federation, each team can: - Define their own GraphQL schema - Deploy and scale their service independently - Contribute to a unified GraphQL API without tight coupling - Maintain ownership of their domain-specific logic -The magic happens through a federated gateway that acts as the central coordinator, composing these separate schemas into a unified schema that clients can query. +The magic happens through a federated gateway that acts as the central coordinator, composing these +separate schemas into a unified schema that clients can query. ## How Federation Works in GraphQL @@ -60,10 +73,10 @@ The federation process involves several key components: - **Subgraphs**: Individual services that define their own GraphQL schemas and resolvers - **Gateway**: A specialized service that sits between clients and your federated services -- **Schema composition**: The process of merging schemas while resolving references between them, often handled by schema registries. +- **Schema composition**: The process of merging schemas while resolving references between them, + often handled by schema registries. - - + ```graphql type Product @key(fields: "id") { @@ -74,8 +87,7 @@ type Product @key(fields: "id") { } ``` - - + ```graphql type Order @key(fields: "id") { @@ -89,8 +101,8 @@ type Product { } ``` - - + + ```graphql type Query { user(id: ID!): User @@ -108,16 +120,18 @@ type Order { } ``` - - + ### Schema Composition -Let's break down schema composition in GraphQL federation with more detail and examples. -Schema composition is the process where multiple subgraph schemas are combined into one unified schema. -It's more complex than simply merging schemas together, though, because it needs to handle relationships, detect incompatibilities, and ensure types are properly connected across services and subgraphs. +Let's break down schema composition in GraphQL federation with more detail and examples. Schema +composition is the process where multiple subgraph schemas are combined into one unified schema. +It's more complex than simply merging schemas together, though, because it needs to handle +relationships, detect incompatibilities, and ensure types are properly connected across services and +subgraphs. -Based on the examples we provided before, here's the unified schema GraphQL clients will see and can query: +Based on the examples we provided before, here's the unified schema GraphQL clients will see and can +query: ```graphql type Query { @@ -145,14 +159,14 @@ type Product { } ``` -This unified schema combines types and fields from all three subgraphs (Users, Orders, and Products), allowing clients to seamlessly query across these domains. +This unified schema combines types and fields from all three subgraphs (Users, Orders, and +Products), allowing clients to seamlessly query across these domains. ### Gateway -The federation gateway is the entry point to your distributed data graph. -It presents a unified GraphQL endpoint to clients -and handles the complexity of routing queries to the appropriate subgraphs and assembling the results, -and often provides caching and performance optimizations. +The federation gateway is the entry point to your distributed data graph. It presents a unified +GraphQL endpoint to clients and handles the complexity of routing queries to the appropriate +subgraphs and assembling the results, and often provides caching and performance optimizations. ```mermaid graph TD @@ -188,62 +202,73 @@ query { } ``` -The gateway will route parts of the query to the appropriate subgraphs, collect the results, -and assemble them into a single response that the client can consume. +The gateway will route parts of the query to the appropriate subgraphs, collect the results, and +assemble them into a single response that the client can consume. ## Benefits of GraphQL Federation ### Domain-Driven Development -Teams can work independently on their services while contributing to a cohesive API. -This autonomy accelerates development and reduces coordination overhead. +Teams can work independently on their services while contributing to a cohesive API. This autonomy +accelerates development and reduces coordination overhead. ### Service Integrity Protection -The schema composition step verifies integration between services -by ensuring that changes in individual subgraphs -do not conflict with other subgraphs. +The schema composition step verifies integration between services by ensuring that changes in +individual subgraphs do not conflict with other subgraphs. ### Scalability and Performance -Subgraphs and services can be scaled independently based on their specific requirements. -The product catalog might need different scaling characteristics than the order processing system. +Subgraphs and services can be scaled independently based on their specific requirements. The product +catalog might need different scaling characteristics than the order processing system. ### Single, Unified API Thanks to GraphQL, clients get a single endpoint with unified schema spanning multiple subgraphs. -The complexity of distributed systems is hidden. -The gateway ensures every query reaches its destination and returns with the right data. +The complexity of distributed systems is hidden. The gateway ensures every query reaches its +destination and returns with the right data. -## Federation vs. Monolithic Architecture +## Is GraphQL Federation Right for You? -While monolithic GraphQL APIs have their place, federated architectures offer several advantages for larger applications: +GraphQL Federation aligns naturally with Domain Driven Design (DDD) principles by allowing teams to +maintain clear boundaries around their domains, while maintaining explicit integration points +through the GraphQL schema. It is particularly valuable for organizations where multiple teams need +to work independently on different parts of the GraphQL API, with the flexibility to use different +technologies and programming languages. -| **Aspect** | **Monolithic GraphQL** | **Federated GraphQL** | -| ----------------- | --------------------------------- | ----------------------------- | -| Development Speed | Initially faster | Better for long-term velocity | -| Team Coordination | Requires significant coordination | Enables independence | -| Deployment | All-or-nothing | Independent deployments | -| Scaling | Entire system scales together | Independent scaling | +However, implementing Federation requires substantial infrastructure support, including a dedicated +team to manage the gateway, schema registry, to help connect subgraphs to the federated API and guide +teams on best practices. -## Real-World Implementations +Before adopting Federation, it's crucial to consider whether your organization truly needs this +level of complexity. -GraphQL Federation is adopted by tech giants such as -[Netlifx](https://netflixtechblog.com/how-netflix-scales-its-api-with-graphql-federation-part-1-ae3557c187e2), +Meta (formerly Facebook), [where GraphQL was created](/blog/2015-09-14-graphql/), has continued to +use a monolithic GraphQL API since 2012. However, companies like +[Netflix](https://netflixtechblog.com/how-netflix-scales-its-api-with-graphql-federation-part-1-ae3557c187e2), [Expedia Group](https://youtu.be/kpeVT7J6Bsw?si=srGWsoxf3kTmneTu&t=79), [Volvo](https://www.apollographql.com/blog/volvo-cars-drives-into-the-future-of-online-car-shopping-with-the-supergraph), -and [Booking](https://youtu.be/2KsP_x50tGk?si=mu-MOG-xZQSDNDjh&t=478). +and [Booking](https://youtu.be/2KsP_x50tGk?si=mu-MOG-xZQSDNDjh&t=478) have adopted Federation to +better align with their organizational structures and microservices architecture. -Many industry leaders successfully use GraphQL federation at scale, proving that federation works reliably for large-scale production applications. +As you see, many industry leaders successfully federated their GraphQL APIs, proving that it works +reliably for large-scale production applications. ## Getting Started with GraphQL Federation -To implement GraphQL federation, organizations should: - -1. **Identify Service Boundaries**: Define clear boundaries between different domains in your application -2. **Design Schemas**: Create schemas that reflect these boundaries while considering how they'll interact -3. **Implement Subgraphs**: Build individual services that implement their portion of the schema -4. **Set Up a federated Gateway**: Deploy a federation gateway to compose and serve the unified schema -5. **Monitor and Optimize**: Implement monitoring and continuously optimize query performance - -Organizations can gradually migrate from a monolithic to federated GraphQL implementation, one service at a time. +If you're considering adopting GraphQL Federation, here are some steps to get started: + +1. **Identify Service Boundaries**: Define clear boundaries between different domains in your + application +2. [**Design Schemas**](/learn/schema/ 'Learn about the different elements of the GraphQL type system'): + Create schemas that reflect these boundaries while considering how they'll interact +3. [**Implement Subgraphs**](/community/tools-and-libraries/?tags=server 'Discover a list of GraphQL servers in our Tools and Libraries page'): + Build individual services that implement their portion of the schema +4. [**Set Up a Gateway**](/community/tools-and-libraries/?tags=gateways-supergraphs 'Discover a list of GraphQL gateways in our Tools and Libraries page'): + Deploy a federation gateway to compose and serve the unified schema +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'): + Manage schema composition and validation to ensure integrity across subgraphs + +When migrating from a monolithic GraphQL API to Federation, the simplest starting point is to treat +your existing schema as your first subgraph. From there, you can follow the steps above to gradually +decompose your schema into smaller pieces. From f35b768d69f9ce2618ec66fb01098876a71215dd Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Wed, 18 Dec 2024 11:59:51 +0100 Subject: [PATCH 09/11] Apply Benjie's feedback --- src/pages/learn/federation.mdx | 48 +++++++++++++++++----------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/src/pages/learn/federation.mdx b/src/pages/learn/federation.mdx index 2891e733f3..dffd1327d1 100644 --- a/src/pages/learn/federation.mdx +++ b/src/pages/learn/federation.mdx @@ -4,21 +4,21 @@ sidebarTitle: Federation import { Tabs } from 'nextra/components' -# GraphQL Federation +# GraphQL federation As applications grow more complex, traditional monolithic approaches often fall short. At scale, monolithic architectures can become cumbersome, brittle, and increasingly hard to test and validate. This has led to a rise in the adoption of new patterns like distributed systems and microservices. -In some ways, GraphQL Federation is like microservices for GraphQL – an architectural pattern that +In some ways, GraphQL federation is like microservices for GraphQL - an architectural pattern that has found particular resonance in the GraphQL ecosystem. -GraphQL Federation gained widespread adoption after +GraphQL federation gained widespread adoption after [Apollo GraphQL introduced Apollo Federation in 2019](https://www.apollographql.com/blog/apollo-federation-f260cf525d21). Their implementation has become a reference point for the GraphQL community, helping establish federation as a standard architectural pattern for building a distributed graph in the GraphQL ecosystem. -With more companies and developers seeing the benefits of building a distributed graph with +With more companies and developers seeing the benefits of building a distributed GraphQL schema with federation, the GraphQL ecosystem is now moving towards standardization of federation patterns. The GraphQL Foundation's [Composite Schema Working Group](https://github.com/graphql/composite-schemas-wg), which includes @@ -50,14 +50,14 @@ Think of the "Login with Google" or "Login with Facebook" buttons you see on web federation in action: you can use your Google or Facebook account to log into many different websites, even though each company manages their own login system separately. -## What Is Federated GraphQL? +## What is federated GraphQL? -GraphQL Federation applies those principles to GraphQL APIs. It enables organizations to build a +GraphQL federation applies those principles to GraphQL APIs. It enables organizations to build a unified GraphQL schema from multiple independent services (most often called subgraphs), each responsible for its portion of the application's data graph. Consider an e-commerce platform: You might have separate teams managing products, user accounts, and -order processing. With GraphQL Federation, each team can: +order processing. With GraphQL federation, each team can: - Define their own GraphQL schema - Deploy and scale their service independently @@ -67,7 +67,7 @@ order processing. With GraphQL Federation, each team can: The magic happens through a federated gateway that acts as the central coordinator, composing these separate schemas into a unified schema that clients can query. -## How Federation Works in GraphQL +## How federation works in GraphQL The federation process involves several key components: @@ -122,7 +122,7 @@ type Order { -### Schema Composition +### Schema composition Let's break down schema composition in GraphQL federation with more detail and examples. Schema composition is the process where multiple subgraph schemas are combined into one unified schema. @@ -205,42 +205,42 @@ query { The gateway will route parts of the query to the appropriate subgraphs, collect the results, and assemble them into a single response that the client can consume. -## Benefits of GraphQL Federation +## Benefits of GraphQL federation -### Domain-Driven Development +### Domain-driven development Teams can work independently on their services while contributing to a cohesive API. This autonomy accelerates development and reduces coordination overhead. -### Service Integrity Protection +### Service integrity protection The schema composition step verifies integration between services by ensuring that changes in individual subgraphs do not conflict with other subgraphs. -### Scalability and Performance +### Scalability and performance Subgraphs and services can be scaled independently based on their specific requirements. The product catalog might need different scaling characteristics than the order processing system. -### Single, Unified API +### Single, unified API Thanks to GraphQL, clients get a single endpoint with unified schema spanning multiple subgraphs. The complexity of distributed systems is hidden. The gateway ensures every query reaches its destination and returns with the right data. -## Is GraphQL Federation Right for You? +## Is GraphQL federation right for you? -GraphQL Federation aligns naturally with Domain Driven Design (DDD) principles by allowing teams to +GraphQL federation aligns naturally with Domain Driven Design (DDD) principles by allowing teams to maintain clear boundaries around their domains, while maintaining explicit integration points through the GraphQL schema. It is particularly valuable for organizations where multiple teams need to work independently on different parts of the GraphQL API, with the flexibility to use different technologies and programming languages. -However, implementing Federation requires substantial infrastructure support, including a dedicated +However, implementing federation requires substantial infrastructure support, including a dedicated team to manage the gateway, schema registry, to help connect subgraphs to the federated API and guide teams on best practices. -Before adopting Federation, it's crucial to consider whether your organization truly needs this +Before adopting federation, it's crucial to consider whether your organization truly needs this level of complexity. Meta (formerly Facebook), [where GraphQL was created](/blog/2015-09-14-graphql/), has continued to @@ -248,15 +248,15 @@ use a monolithic GraphQL API since 2012. However, companies like [Netflix](https://netflixtechblog.com/how-netflix-scales-its-api-with-graphql-federation-part-1-ae3557c187e2), [Expedia Group](https://youtu.be/kpeVT7J6Bsw?si=srGWsoxf3kTmneTu&t=79), [Volvo](https://www.apollographql.com/blog/volvo-cars-drives-into-the-future-of-online-car-shopping-with-the-supergraph), -and [Booking](https://youtu.be/2KsP_x50tGk?si=mu-MOG-xZQSDNDjh&t=478) have adopted Federation to +and [Booking](https://youtu.be/2KsP_x50tGk?si=mu-MOG-xZQSDNDjh&t=478) have adopted federation to better align with their organizational structures and microservices architecture. -As you see, many industry leaders successfully federated their GraphQL APIs, proving that it works -reliably for large-scale production applications. +As you see, some of the world's largest industry leaders have successfully federated their GraphQL APIs, +proving that it works reliably for production applications at an extraordinary scale. -## Getting Started with GraphQL Federation +## Getting started with GraphQL federation -If you're considering adopting GraphQL Federation, here are some steps to get started: +If you're considering adopting GraphQL federation, here are some steps to get started: 1. **Identify Service Boundaries**: Define clear boundaries between different domains in your application @@ -269,6 +269,6 @@ If you're considering adopting GraphQL Federation, here are some steps to get st 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'): Manage schema composition and validation to ensure integrity across subgraphs -When migrating from a monolithic GraphQL API to Federation, the simplest starting point is to treat +When migrating from a monolithic to federated GraphQL API, the simplest starting point is to treat your existing schema as your first subgraph. From there, you can follow the steps above to gradually decompose your schema into smaller pieces. From a0e50d6bfce0cbe1f148a0a6b0f97f0401421ba6 Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Wed, 18 Dec 2024 12:09:37 +0100 Subject: [PATCH 10/11] Make it clear you do not need federation on day 1 --- src/pages/learn/federation.mdx | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/src/pages/learn/federation.mdx b/src/pages/learn/federation.mdx index dffd1327d1..2d72591074 100644 --- a/src/pages/learn/federation.mdx +++ b/src/pages/learn/federation.mdx @@ -237,11 +237,12 @@ to work independently on different parts of the GraphQL API, with the flexibilit technologies and programming languages. However, implementing federation requires substantial infrastructure support, including a dedicated -team to manage the gateway, schema registry, to help connect subgraphs to the federated API and guide -teams on best practices. +team to manage the gateway, schema registry, to help connect subgraphs to the federated API and +guide teams on best practices. Before adopting federation, it's crucial to consider whether your organization truly needs this -level of complexity. +level of complexity. You can start with a monolithic setup and transition to federation as your needs +evolve, rather than implementing it prematurely. Meta (formerly Facebook), [where GraphQL was created](/blog/2015-09-14-graphql/), has continued to use a monolithic GraphQL API since 2012. However, companies like @@ -251,8 +252,8 @@ use a monolithic GraphQL API since 2012. However, companies like and [Booking](https://youtu.be/2KsP_x50tGk?si=mu-MOG-xZQSDNDjh&t=478) have adopted federation to better align with their organizational structures and microservices architecture. -As you see, some of the world's largest industry leaders have successfully federated their GraphQL APIs, -proving that it works reliably for production applications at an extraordinary scale. +As you see, some of the world's largest industry leaders have successfully federated their GraphQL +APIs, proving that it works reliably for production applications at an extraordinary scale. ## Getting started with GraphQL federation From 628c2e863b117f0a7a20a61424186caca9842582 Mon Sep 17 00:00:00 2001 From: Kamil Kisiela Date: Mon, 20 Jan 2025 12:12:17 +0100 Subject: [PATCH 11/11] Apply suggestions - intro --- src/pages/learn/federation.mdx | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/src/pages/learn/federation.mdx b/src/pages/learn/federation.mdx index 2d72591074..6de592bc37 100644 --- a/src/pages/learn/federation.mdx +++ b/src/pages/learn/federation.mdx @@ -6,11 +6,7 @@ import { Tabs } from 'nextra/components' # GraphQL federation -As applications grow more complex, traditional monolithic approaches often fall short. At scale, -monolithic architectures can become cumbersome, brittle, and increasingly hard to test and validate. -This has led to a rise in the adoption of new patterns like distributed systems and microservices. -In some ways, GraphQL federation is like microservices for GraphQL - an architectural pattern that -has found particular resonance in the GraphQL ecosystem. +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. GraphQL federation gained widespread adoption after [Apollo GraphQL introduced Apollo Federation in 2019](https://www.apollographql.com/blog/apollo-federation-f260cf525d21).