From c5ee0f52aced002f3e2232207752a95ae463eff9 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Tue, 7 Nov 2023 17:03:40 -0700 Subject: [PATCH 01/42] Restructure --- docs/source/index.mdx | 125 +++++++++--------------------------------- 1 file changed, 25 insertions(+), 100 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 8ca0c7fd7..105158a33 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -1,129 +1,54 @@ --- title: Introduction to Apollo Federation -description: Combine GraphQL APIs into a unified supergraph +subtitle: Combine GraphQL APIs into a unified supergraph +description: Learn how Apollo Federation can help you combine your GraphQL APIs into a unified, federated supergraph --- -**Apollo Federation** is a powerful, open architecture for creating a **supergraph** that combines multiple GraphQL APIs: +
-```mermaid -graph LR; - clients(Clients); - subgraph "Supergraph"; - gateway([Router]); - serviceA[Users
subgraph]; - serviceB[Products
subgraph]; - gateway --- serviceA & serviceB; - end; - clients -.- gateway; - class clients secondary; -``` +This page covers: +- What Apollo Federation is +- The benefits of using Apollo Federation +- The resources you can use to learn about federation -With federation, you can responsibly share ownership of your supergraph 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](/graphos/) provides a managed mode for Apollo Federation, which helps you modify and grow your supergraph without any downtime. +## What is Apollo Federation? -
- - Get started with Federation - - -
+**Apollo Federation** is a microservices architecture that combines multiple GraphQL APIs. +In this federated architecture, your individual GraphQL APIs are called **subgraphs** and they're combined into a **supergraph**. -## How it works +Subgraphs can each use any [subgraph-compatible GraphQL server library](./building-supergraphs/supported-subgraphs/). This includes Apollo Server using special extensions from the [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph) library. Different subgraphs in the same supergraph can use different server libraries. -In a federated architecture, your individual GraphQL APIs are called **subgraphs**, and they're composed into a **supergraph**. By querying your supergraph's router, clients can fetch data from all of your subgraphs with a single request: +A supergraph consists of more than just subgraphs—it also includes a **router** that acts as an API gateway for your subgraphs. +By querying your supergraph's router, clients can fetch data from all of your subgraphs with a single request: ```mermaid graph LR; clients(Clients); subgraph "Supergraph"; - gateway([Router]); - serviceA[Users
subgraph]; - serviceB[Products
subgraph]; - gateway --- serviceA & serviceB; + router([Router]); + serviceA[Subgraph A]; + serviceB[Subgraph B]; + router --- serviceA & serviceB; end; - clients -.- gateway; + clients -.- router; class clients secondary; ``` -The **router** serves as the public access point for your supergraph. It receives incoming GraphQL operations and intelligently routes them across your subgraphs. 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 subgraph has its own schema: - - - -```graphql title="Users subgraph" -type User { - id: ID! - name: String! -} -``` - -```graphql title="Products subgraph" -type Product { - upc: String! - inStock: Boolean! -} -``` - - - -To communicate with all of your subgraphs, the router uses a special **supergraph schema** that _combines_ these subgraph schemas. - -Supergraph schemas are created via a process called **composition**. Composition takes all of your subgraph schemas and intelligently combines them into _one_ schema for your router: - -```graphql title="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 router _which_ subgraph is responsible for _which_ types and fields. [Learn more about composition.](./federated-types/composition/) - -### Server instances - -In a federated architecture, each subgraph instance is a GraphQL service that's queried _only_ by the router. The router is a separate service that exposes a GraphQL endpoint to external clients. Clients query the router, and the router then queries individual subgraphs to obtain, combine, and return results: - -```mermaid -graph LR; - clients(Clients); - subgraph "Supergraph"; - gateway([Router]); - serviceA[Users
subgraph]; - serviceB[Products
subgraph]; - gateway --- serviceA & serviceB; - end; - clients -.- gateway; - class clients secondary; -``` +The router serves as the public access point for your supergraph. Each subgraph is queried _only_ by the router. It receives incoming GraphQL operations and intelligently routes them across your subgraphs. The router receives responses from the subgraphs and returns a single response to the client. **For clients, this looks exactly the same as querying any other GraphQL server.** No client-side configuration is required. **The router** is one of the following: - [The Apollo Router](https://www.apollographql.com/docs/router/) (recommended): a high-performance, precompiled Rust executable - If you're getting started with federation, we recommend [creating a **cloud supergraph**](/graphos/quickstart/cloud/) with Apollo GraphOS. With a cloud supergraph, GraphOS provisions and manages your router for you! -- An instance of Apollo Server using special extensions from the [`@apollo/gateway`](/apollo-server/using-federation/api/apollo-gateway) library +- [To-do]() Other routers in the ecosystem. + + -**Subgraphs** can each use any [subgraph-compatible GraphQL server library](./building-supergraphs/supported-subgraphs/). +- An instance of Apollo Server using special extensions from the [`@apollo/gateway`](/apollo-server/using-federation/api/apollo-gateway) library -- This includes Apollo Server using special extensions from the [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph) library. -- Different subgraphs in the same supergraph can use different server libraries. + ## Benefits of federation From 00f5a221b00815df8c4276088386bde9cc8b47a6 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Wed, 8 Nov 2023 10:46:35 -0700 Subject: [PATCH 02/42] Rewrite intro --- docs/source/index.mdx | 38 +++++++++++++++++++++++--------------- 1 file changed, 23 insertions(+), 15 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 105158a33..df9511b79 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -6,7 +6,10 @@ description: Learn how Apollo Federation can help you combine your GraphQL APIs
-This page covers: +💡 What you'll learn: + +
+ - What Apollo Federation is - The benefits of using Apollo Federation - The resources you can use to learn about federation @@ -15,13 +18,11 @@ This page covers: ## What is Apollo Federation? -**Apollo Federation** is a microservices architecture that combines multiple GraphQL APIs. +**Apollo Federation** is an architecture that combines multiple GraphQL APIs. In this federated architecture, your individual GraphQL APIs are called **subgraphs** and they're combined into a **supergraph**. -Subgraphs can each use any [subgraph-compatible GraphQL server library](./building-supergraphs/supported-subgraphs/). This includes Apollo Server using special extensions from the [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph) library. Different subgraphs in the same supergraph can use different server libraries. - -A supergraph consists of more than just subgraphs—it also includes a **router** that acts as an API gateway for your subgraphs. -By querying your supergraph's router, clients can fetch data from all of your subgraphs with a single request: +A supergraph consists of more than just subgraphs though. It also includes a **router** that acts as an API gateway for your subgraphs. +By querying your supergraph's router, clients can fetch data from all of your subgraphs with a single request. ```mermaid graph LR; @@ -30,25 +31,32 @@ graph LR; router([Router]); serviceA[Subgraph A]; serviceB[Subgraph B]; - router --- serviceA & serviceB; + serviceC[Subgraph C]; + router --- serviceA & serviceB & serviceC; end; clients -.- router; class clients secondary; ``` -The router serves as the public access point for your supergraph. Each subgraph is queried _only_ by the router. It receives incoming GraphQL operations and intelligently routes them across your subgraphs. The router receives responses from the subgraphs and returns a single response to the client. **For clients, this looks exactly the same as querying any other GraphQL server.** No client-side configuration is required. +### Subgraphs +Subgraphs can use any [subgraph-compatible GraphQL server library](./building-supergraphs/supported-subgraphs/). This includes Apollo Server using special extensions from the [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph) library. +Different subgraphs in the same supergraph can use different server libraries. + +### Router + +The router is a separate service that exposes a GraphQL endpoint to external clients. It serves as the public access point for your supergraph. Only the router queries subgraphs—client never do so directly. + +The router receives incoming GraphQL operations and intelligently routes them across your subgraphs. The router then receives responses from the subgraphs and returns a single response to the client. **For clients, the request and response cycle looks exactly the same as querying any other GraphQL server.** No client-side configuration is required. -**The router** is one of the following: +For your router, Apollo recommends using [the Apollo Router](/router/)—[a high-performance, precompiled executable](https://www.apollographql.com/blog/announcement/backend/apollo-router-our-graphql-federation-runtime-in-rust/)—but other options compatible with Apollo Federation are available. An instance of Apollo Server using special extensions from the [`@apollo/gateway`](/apollo-server/using-federation/api/apollo-gateway) library can also act as a router, but Apollo recommends using the Apollo Router for its performance and security benefits. -- [The Apollo Router](https://www.apollographql.com/docs/router/) (recommended): a high-performance, precompiled Rust executable - - If you're getting started with federation, we recommend [creating a **cloud supergraph**](/graphos/quickstart/cloud/) with Apollo GraphOS. With a cloud supergraph, GraphOS provisions and manages your router for you! -- [To-do]() Other routers in the ecosystem. + - +If you're just getting started with federation, we recommend [creating a cloud supergraph](./quickstart/cloud/) with Apollo GraphOS. With a cloud supergraph, GraphOS provisions and manages your router for you. -- An instance of Apollo Server using special extensions from the [`@apollo/gateway`](/apollo-server/using-federation/api/apollo-gateway) library + - +To learn more about the Apollo Router as an API gateway and when to consider it, see the related [Tech Note](https://www.apollographql.com/docs/technotes/TN0037-api-gateways/). ## Benefits of federation From bc48c9bec4c8bccd4e407a1db73b9b228b2e2198 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Wed, 8 Nov 2023 11:16:38 -0700 Subject: [PATCH 03/42] Add resources --- docs/source/index.mdx | 42 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 37 insertions(+), 5 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index df9511b79..952fe4cfd 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -12,7 +12,7 @@ description: Learn how Apollo Federation can help you combine your GraphQL APIs - What Apollo Federation is - The benefits of using Apollo Federation -- The resources you can use to learn about federation +- The resources you can use to learn more about federation
@@ -44,11 +44,11 @@ Different subgraphs in the same supergraph can use different server libraries. ### Router -The router is a separate service that exposes a GraphQL endpoint to external clients. It serves as the public access point for your supergraph. Only the router queries subgraphs—client never do so directly. +The router is a separate service that exposes a GraphQL endpoint to external clients. It serves as the public access point for your supergraph. _Only_ the router queries subgraphs—client never do so directly. -The router receives incoming GraphQL operations and intelligently routes them across your subgraphs. The router then receives responses from the subgraphs and returns a single response to the client. **For clients, the request and response cycle looks exactly the same as querying any other GraphQL server.** No client-side configuration is required. +The router receives incoming GraphQL operations from clients and intelligently routes them across your subgraphs. The router then receives responses from the subgraphs and returns a single response to the client. **For clients, the request and response cycle looks exactly the same as querying any other GraphQL server.** No client-side configuration is required. -For your router, Apollo recommends using [the Apollo Router](/router/)—[a high-performance, precompiled executable](https://www.apollographql.com/blog/announcement/backend/apollo-router-our-graphql-federation-runtime-in-rust/)—but other options compatible with Apollo Federation are available. An instance of Apollo Server using special extensions from the [`@apollo/gateway`](/apollo-server/using-federation/api/apollo-gateway) library can also act as a router, but Apollo recommends using the Apollo Router for its performance and security benefits. +For your router, Apollo recommends using [the Apollo Router](/router/)—[a high-performance, precompiled executable](https://www.apollographql.com/blog/announcement/backend/apollo-router-our-graphql-federation-runtime-in-rust/)—but other options compatible with Apollo Federation are available. An instance of Apollo Server using special extensions from the [`@apollo/gateway`](/apollo-server/using-federation/api/apollo-gateway) library can also act as a router, but Apollo recommends using the Apollo Router for its performance and security benefits. [Learn more.](/building-supergraphs/router) @@ -300,4 +300,36 @@ This mode helps multiple teams working on a supergraph to coordinate when and ho --- -Ready to try out Apollo Federation? [Jump into the Quickstart](./quickstart/setup/)! +## Next steps + +Depending on your goals, you have several options for learning more about federation. Apollo's docs offer these sections: + +- A [Quickstart tutorial](./quickstart/setup/) that walks you through setting up an Apollo Federation supergraph +- More details on [subgraphs](./building-supergraphs/subgraphs-overview) and [routers](./building-supergraphs/router) +- A conceptual overview of writing [federated schemas](./federated-types/) +- A [guide on using Apollo GraphOS](./managed-federation) to automate and manage deployments of your federated schemas +- Reference materials for: + - [Performance coniderations](./performance/caching) + - [Debugging and metrics](./errors) + - [Subgraph specifications](./building-supergraphs/router) +- A [migration guide from Federation 1 to Federation 2](/federation-2/moving-to-federation-2) + +### Additional resources + +Outside of the docs, Apollo offers these resources for learning more about federation: + +- A general [overview of federated architecture](https://graphql.com/learn/federated-architecture/) +- An [interactive course](https://www.apollographql.com/tutorials/voyage-part1) focused on Apollo Federation +- A [demo app](https://github.com/apollographql/supergraph-demo-fed2) that you can fork and tinker with +- The [overview video](https://youtu.be/wRExDdgs6JU) embedded below: + + + + + + + + + + + From c8aad38471c1b78a4325756c715a4599a99a7a91 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Wed, 8 Nov 2023 15:24:27 -0700 Subject: [PATCH 04/42] Add benefits --- docs/source/index.mdx | 298 ++++++++++-------------------------------- 1 file changed, 71 insertions(+), 227 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 952fe4cfd..0ed633297 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -1,28 +1,26 @@ --- title: Introduction to Apollo Federation -subtitle: Combine GraphQL APIs into a unified supergraph +subtitle: Learn how to combine your GraphQL APIs into a unified supergraph description: Learn how Apollo Federation can help you combine your GraphQL APIs into a unified, federated supergraph --- -
+## What is Apollo Federation? -💡 What you'll learn: +**Apollo Federation** is an architecture that combines multiple GraphQL APIs. +In this federated architecture, your individual GraphQL APIs are called **subgraphs**, and they're combined into a **supergraph**. -
+Different subgraphs in the same supergraph can use different server libraries, as long as they are [federation-compatible](./building-supergraphs/supported-subgraphs/). This includes Apollo Server using special extensions from the [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph) library. -- What Apollo Federation is -- The benefits of using Apollo Federation -- The resources you can use to learn more about federation + -
+Learn more about [choosing a subgraph library](./building-supergraphs/subgraphs-overview#choosing-a-subgraph-library). -## What is Apollo Federation? + -**Apollo Federation** is an architecture that combines multiple GraphQL APIs. -In this federated architecture, your individual GraphQL APIs are called **subgraphs** and they're combined into a **supergraph**. +### The role of the router -A supergraph consists of more than just subgraphs though. It also includes a **router** that acts as an API gateway for your subgraphs. -By querying your supergraph's router, clients can fetch data from all of your subgraphs with a single request. +A supergraph consists of more than just subgraphs, though. It also includes a **router** that acts as an API gateway for your subgraphs. +Clients can fetch data from all your subgraphs with a single request by querying your supergraph's router. ```mermaid graph LR; @@ -38,34 +36,32 @@ graph LR; class clients secondary; ``` -### Subgraphs -Subgraphs can use any [subgraph-compatible GraphQL server library](./building-supergraphs/supported-subgraphs/). This includes Apollo Server using special extensions from the [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph) library. -Different subgraphs in the same supergraph can use different server libraries. - -### Router - -The router is a separate service that exposes a GraphQL endpoint to external clients. It serves as the public access point for your supergraph. _Only_ the router queries subgraphs—client never do so directly. +The router is a separate service that exposes a GraphQL endpoint to external clients. It serves as the public access point for your supergraph. _Only_ the router queries subgraphs—clients never do so directly. -The router receives incoming GraphQL operations from clients and intelligently routes them across your subgraphs. The router then receives responses from the subgraphs and returns a single response to the client. **For clients, the request and response cycle looks exactly the same as querying any other GraphQL server.** No client-side configuration is required. - -For your router, Apollo recommends using [the Apollo Router](/router/)—[a high-performance, precompiled executable](https://www.apollographql.com/blog/announcement/backend/apollo-router-our-graphql-federation-runtime-in-rust/)—but other options compatible with Apollo Federation are available. An instance of Apollo Server using special extensions from the [`@apollo/gateway`](/apollo-server/using-federation/api/apollo-gateway) library can also act as a router, but Apollo recommends using the Apollo Router for its performance and security benefits. [Learn more.](/building-supergraphs/router) +The router receives incoming GraphQL operations from clients and intelligently routes them across your subgraphs. The router then receives subgraph responses and returns a single response to the client. **For clients, the request and response cycle looks exactly the same as querying any other GraphQL server.** No client-side configuration is required. -If you're just getting started with federation, we recommend [creating a cloud supergraph](./quickstart/cloud/) with Apollo GraphOS. With a cloud supergraph, GraphOS provisions and manages your router for you. +Learn more about [your router options](./building-supergraphs/router). -To learn more about the Apollo Router as an API gateway and when to consider it, see the related [Tech Note](https://www.apollographql.com/docs/technotes/TN0037-api-gateways/). +## Benefits of federation + +As a GraphQL-native microservices architecture, Apollo Federation draws on both paradigms' benefits. +Federated architecture imparts some unique additional benefits by combining GraphQL and microservices frameworks. +Continue reading to learn more. + -## Benefits of federation +- Learn more about the [considerations and benefits of GraphQL](/intro/benefits/). +- Learn more about the [considerations and benefits of microservices architecture](https://aws.amazon.com/compare/the-difference-between-monolithic-and-microservices-architecture/). -### 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: +### Challenges of separate services -

❌

+Sometimes, when an organization adopts GraphQL, multiple teams do so independently. Each team sets up a GraphQL services that provides the data used by that team. For example, a travel app may have separate GraphQL servicess for users, flights, and hotels: ```mermaid graph RL; @@ -76,229 +72,77 @@ graph RL; end; subgraph " "; - databaseB[(Product
data)]; - serviceB[Products API]; + databaseB[(Flight
data)]; + serviceB[Flights API]; databaseB --- serviceB; end; + subgraph " "; + databaseC[(Hotel
data)]; + serviceC[Hotels API]; + databaseC --- serviceC; + end; + clients(Clients); - serviceA & serviceB -.- clients; + serviceA & serviceB & serviceC -.- clients; class clients secondary; ``` -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. +But with an architecture like this, a client might need to communicate with _multiple_ APIs to fetch all the data it needs. This diminishes a powerful advantage of GraphQL over traditional REST APIs. + +To counter this, some organizations "stitch" schemas together. Schema stitching links types across services and provides the client with one endpoint to query. The ever-growing complexity of schema stitching can be [challenging to manage](https://www.apollographql.com/blog/announcement/expedia-improved-performance-by-moving-from-schema-stitching-to-apollo-federation/) though. -Instead, your organization should expose a [unified supergraph](https://principledgraphql.com/integrity) that lets clients fetch _all_ of the data that they need from a single endpoint: +### Challenges of monoliths -

✅

+Alternatively, some organizations adopting GraphQL may start with a monolithic GraphQL server, allowing clients to fetch all the needed data with one request. ```mermaid -graph LR; +flowchart LR; + databaseA[(Users
data)]; + databaseB[(Flights
data)]; + databaseC[(Hotels
data)]; + server(["Monolithic
GraphQL server"]); + server --- databaseA & databaseB & databaseC; clients(Clients); - subgraph "Supergraph"; - gateway([Router]); - serviceA[Users
subgraph]; - serviceB[Products
subgraph]; - gateway --- serviceA & serviceB; - end; - clients -.- gateway; + clients -.- server class clients secondary; + class teamA,teamB,teamC tertiary; ``` -By unifying your supergraph 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: - -

❌

- -```mermaid -flowchart TB; - teamA{Users
team}; - teamB{Flights
team}; - teamC{Hotels
team}; - teamD{Billing
team}; - teamE{Bookings
team}; - server(["Monolith
GraphQL server"]); - teamA & teamB & teamC & teamD & teamE -.- server; - class teamA,teamB,teamC,teamD,teamE tertiary; -``` +Representing an entire enterprise-scale graph as a monolith has its own challenges. Performance might degrade as your users and features increase. Developer productivity can lag due to coordination challenges of committing changes to the same application. -With a supergraph, you can reduce performance _and_ productivity bottlenecks simultaneously. Each team can maintain their own subgraph(s) independently, and your supergraph's router serves primarily to _route_ incoming operations, not to resolve each of them completely. +### A non-monolithic unifed graph -

✅

+With a [unified supergraph](https://principledgraphql.com/integrity), you can reduce performance and productivity bottlenecks simultaneously, without the additional complexity of schema stitching. Each team can own and develop their subgraph(s) independently because your supergraph's router serves primarily to route incoming operations, not to resolve each of them completely. This allows clients to fetch data from all subgraphs with a single query without the drawbacks of monolithic architecture or schema stitching. ```mermaid -graph TB; - teamA{Users
team}; - teamB{Flights
team}; - teamC{Hotels
team}; - teamD{Billing
team}; - teamE{Bookings
team}; - serviceA[Users
subgraph]; - serviceB[Flights
subgraph]; - serviceC[Hotels
subgraph]; - serviceD[Billing
subgraph]; - serviceE[Bookings
subgraph]; - teamA -.- serviceA; - teamB -.- serviceB; - teamC -.- serviceC; - teamD -.- serviceD; - teamE -.- serviceE; - gateway([Router]); - serviceA & serviceB & serviceC & serviceD & serviceE --- gateway; - maintainers{Graph
team}; - gateway -.- maintainers; - class teamA,teamB,teamC,teamD,teamE,maintainers tertiary; +graph LR; + clients(Clients); + subgraph "Supergraph"; + router([Router]); + serviceA[Users Subgraph]; + serviceB[Flights Subgraph]; + serviceC[Hotels Subgraph]; + databaseA[(Users
data)]; + databaseB[(Flights
data)]; + databaseC[(Hotels
data)]; + serviceA --- databaseA; + serviceB --- databaseB; + serviceC --- databaseC; + router --- serviceA & serviceB & serviceC; + end; + clients -.- router; + class clients secondary; ``` -In this structure, the "graph team" might be a separate team that's dedicated to maintaining your router as part of back-end infrastructure, or it might be a "meta team" that includes representatives from other teams that maintain subgraphs. - -### Adopt incrementally +#### Incremental adoption As with the rest of the Apollo platform, you can (and should) adopt Apollo Federation **incrementally**: * If you currently use a monolithic GraphQL server, you can break its functionality out one subgraph at a time. * If you currently use a different federated architecture (such as schema stitching), you can [add federation support to your existing services one at a time](./migrating-from-stitching/). -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](https://en.wikipedia.org/wiki/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 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 subgraph would define a `Product` type, and so on: - -

❌

- - - -```graphql title="Users subgraph" -type User { - id: ID! - name: String - reviews: [Review] - purchases: [Product] -} -``` - -```graphql title="Products subgraph" -type Product { - id: ID! - name: String - price: String - reviews: [Review] -} -``` - -```graphql title="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 subgraphs. - -Consider the `User.purchases` field above. Even though this field belongs to the `User` type, a list of `Product`s 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: - -> Some federation-specific syntax is omitted here for clarity. For details, see [Entities](./entities/). - -

✅

- - - -```graphql title="Users subgraph" -type User { - id: ID! - name: String -} -``` - -```graphql title="Products subgraph" -type Product { - id: ID! - name: String - price: String -} - -type User { - id: ID! - purchases: [Product] -} -``` - -```graphql title="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 subgraph _mostly_ defines types and fields 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 subgraph 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](./entities/). - -These resulting schemas provide 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 - -Your router can operate in **managed federation** mode, where [Apollo GraphOS](/graphos/) acts as the source of truth for your supergraph's configuration: - -```mermaid -graph LR; - subgraph "Your infrastructure" - serviceA[Products
subgraph]; - serviceB[Reviews
subgraph]; - gateway([Router]); - end - subgraph "Apollo GraphOS" - registry{{Apollo Schema
Registry}}; - uplink{{Apollo
Uplink}} - end - serviceA & serviceB -->|Publishes
schema| registry; - registry -->|Updates
supergraph config| uplink; - gateway -->|Polls for supergraph changes| uplink; - class registry secondary; - class uplink secondary; -``` - -This mode helps multiple teams working on a supergraph to coordinate when and how to change individual subgraphs. It's recommended for all supergraphs. For more information, read [Managed federation overview](./managed-federation/overview/). - ---- +In both cases, all your clients continue to work throughout your incremental adoption. Clients have no way to distinguish between different graph implementations. ## Next steps @@ -308,11 +152,11 @@ Depending on your goals, you have several options for learning more about federa - More details on [subgraphs](./building-supergraphs/subgraphs-overview) and [routers](./building-supergraphs/router) - A conceptual overview of writing [federated schemas](./federated-types/) - A [guide on using Apollo GraphOS](./managed-federation) to automate and manage deployments of your federated schemas +- A [migration guide from Federation 1 to Federation 2](/federation-2/moving-to-federation-2) - Reference materials for: - - [Performance coniderations](./performance/caching) + - [Performance considerations](./performance/caching) - [Debugging and metrics](./errors) - [Subgraph specifications](./building-supergraphs/router) -- A [migration guide from Federation 1 to Federation 2](/federation-2/moving-to-federation-2) ### Additional resources From 67492c2808f9323245a71c7e7d2c56bcc0b1dbdd Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Wed, 8 Nov 2023 16:33:45 -0700 Subject: [PATCH 05/42] Copyedit --- docs/source/index.mdx | 41 +++++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 0ed633297..7a707df5c 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -6,21 +6,24 @@ description: Learn how Apollo Federation can help you combine your GraphQL APIs ## What is Apollo Federation? -**Apollo Federation** is an architecture that combines multiple GraphQL APIs. -In this federated architecture, your individual GraphQL APIs are called **subgraphs**, and they're combined into a **supergraph**. +**Apollo Federation** is an open standard to combine multiple GraphQL APIs. +In a federated architecture, your individual GraphQL APIs are called **subgraphs**, and they're combined into a **supergraph**. Different subgraphs in the same supergraph can use different server libraries, as long as they are [federation-compatible](./building-supergraphs/supported-subgraphs/). This includes Apollo Server using special extensions from the [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph) library. -Learn more about [choosing a subgraph library](./building-supergraphs/subgraphs-overview#choosing-a-subgraph-library). +Learn more about [choosing subgraph libraries](./building-supergraphs/subgraphs-overview#choosing-a-subgraph-library). ### The role of the router -A supergraph consists of more than just subgraphs, though. It also includes a **router** that acts as an API gateway for your subgraphs. -Clients can fetch data from all your subgraphs with a single request by querying your supergraph's router. +A supergraph consists of more than just subgraphs. It also includes a **router** that acts as an API gateway for your subgraphs. +The router is a separate service that exposes a GraphQL endpoint to external clients. + +Clients can fetch data from all your subgraphs with a single request to the router. The router receives incoming GraphQL operations from clients and intelligently routes them across your subgraphs. The router then receives subgraph responses and returns a single response to the client. + ```mermaid graph LR; @@ -36,9 +39,7 @@ graph LR; class clients secondary; ``` -The router is a separate service that exposes a GraphQL endpoint to external clients. It serves as the public access point for your supergraph. _Only_ the router queries subgraphs—clients never do so directly. - -The router receives incoming GraphQL operations from clients and intelligently routes them across your subgraphs. The router then receives subgraph responses and returns a single response to the client. **For clients, the request and response cycle looks exactly the same as querying any other GraphQL server.** No client-side configuration is required. +Clients only query the router—never subgraphs directly—and only the router queries subgraphs. **For clients, the request and response cycle of querying the router looks exactly the same as querying any other GraphQL server.** No client-side configuration is required. @@ -94,7 +95,7 @@ To counter this, some organizations "stitch" schemas together. Schema stitching ### Challenges of monoliths -Alternatively, some organizations adopting GraphQL may start with a monolithic GraphQL server, allowing clients to fetch all the needed data with one request. +Alternatively, some organizations adopting GraphQL may start with a monolithic GraphQL server, allowing clients to fetch all necessary data with one request. ```mermaid flowchart LR; @@ -109,11 +110,11 @@ flowchart LR; class teamA,teamB,teamC tertiary; ``` -Representing an entire enterprise-scale graph as a monolith has its own challenges. Performance might degrade as your users and features increase. Developer productivity can lag due to coordination challenges of committing changes to the same application. +Representing an entire enterprise-scale graph as a monolith has its own challenges. Performance might degrade as your users and features increase. Developer productivity can lag due to the coordination challenges of different teams committing changes to the same application. ### A non-monolithic unifed graph -With a [unified supergraph](https://principledgraphql.com/integrity), you can reduce performance and productivity bottlenecks simultaneously, without the additional complexity of schema stitching. Each team can own and develop their subgraph(s) independently because your supergraph's router serves primarily to route incoming operations, not to resolve each of them completely. This allows clients to fetch data from all subgraphs with a single query without the drawbacks of monolithic architecture or schema stitching. +With a [unified supergraph](https://principledgraphql.com/integrity), you can reduce performance and productivity bottlenecks, without the additional complexity of schema stitching. Each team can own and develop their subgraph(s) independently because your supergraph's router serves primarily to route incoming operations, not to resolve each of them completely. This allows clients to fetch data from all subgraphs with a single query without the drawbacks of monolithic architecture or schema stitching. ```mermaid graph LR; @@ -139,24 +140,24 @@ graph LR; As with the rest of the Apollo platform, you can (and should) adopt Apollo Federation **incrementally**: -* If you currently use a monolithic GraphQL server, you can break its functionality out one subgraph at a time. * If you currently use a different federated architecture (such as schema stitching), you can [add federation support to your existing services one at a time](./migrating-from-stitching/). +* If you currently use a monolithic GraphQL server, you can break its functionality out one subgraph at a time. -In both cases, all your clients continue to work throughout your incremental adoption. Clients have no way to distinguish between different graph implementations. +In both cases, all your clients continue to work throughout your incremental adoption. ## Next steps Depending on your goals, you have several options for learning more about federation. Apollo's docs offer these sections: - A [Quickstart tutorial](./quickstart/setup/) that walks you through setting up an Apollo Federation supergraph -- More details on [subgraphs](./building-supergraphs/subgraphs-overview) and [routers](./building-supergraphs/router) -- A conceptual overview of writing [federated schemas](./federated-types/) -- A [guide on using Apollo GraphOS](./managed-federation) to automate and manage deployments of your federated schemas -- A [migration guide from Federation 1 to Federation 2](/federation-2/moving-to-federation-2) +- Details on [subgraphs](./building-supergraphs/subgraphs-overview) and [routers](./building-supergraphs/router) in **Building Your Supergraph** +- A conceptual overview of writing [**Federated Schemas**](./federated-types/) +- A [guide on using Apollo GraphOS](./managed-federation) to automate and manage deployments of your federated schemas (this is also known as **Managed Federation**) - Reference materials for: - - [Performance considerations](./performance/caching) - - [Debugging and metrics](./errors) - - [Subgraph specifications](./building-supergraphs/router) + - [**Performance** considerations](./performance/caching) + - [**Debugging and metrics**](./errors) + - [Subgraph specifications](./building-supergraphs/router) for federation-compatibility +- A [migration guide from Federation 1 to Federation 2](/federation-2/moving-to-federation-2) ### Additional resources From b824809f9670226d5639b9f101ad262c2aa3fac3 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Wed, 8 Nov 2023 21:07:24 -0800 Subject: [PATCH 06/42] WIP: update docs for blue-green deploys --- docs/source/managed-federation/deployment.mdx | 91 ++++++++++++++++++- docs/source/managed-federation/setup.mdx | 18 ++-- 2 files changed, 97 insertions(+), 12 deletions(-) diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index 48d6b7ce0..abe1d1e75 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -1,6 +1,7 @@ --- -title: Deploying with managed federation -description: Best practices +title: Deployment best practices +subtitle: Best practices and workflows for deploying with managed federation +description: Best practices and workflows for deploying with managed federation --- When rolling out changes to a [subgraph](../building-supergraphs/subgraphs-overview/), we recommend the following workflow: @@ -117,11 +118,93 @@ The next time it starts up or polls, your router obtains an updated configuratio ## Using variants to control rollout -With managed federation, you can control which version of your graph a fleet of routers are using. In the majority of cases, rolling over all of your router instances to a new schema version is safe, assuming you've used [schema checks](./federated-schema-checks/) to confirm that your changes are backward compatible. +Your deployment model may require deploying a specific version of your graph, for example for blue-green deployments or canary deployments. With managed federation, you can control which version of your graph a fleet of routers are using. In the majority of cases, rolling over all of your router instances to a new schema version is safe, assuming you've used [schema checks](./federated-schema-checks/) to confirm that your changes are backward compatible. However, changes at the router level might involve a variety of different updates, such as [migrating entities](../entities-advanced/#migrating-entities-and-fields) from one subgraph to another. If your infrastructure requires a more advanced deployment process, you can use [graph variants](/graphos/graphs/#variants) to manage different fleets of routers running with different configurations. -### Example +Specifically, for deployments that run in different production environments, such as blue-green deployments, you can configure your environments to refer to a single graph variant by pinning the supergraph schema of each environment to your routers at deployment time. Using a single variant between different production environments enables Studio to get usage reports and do analysis on the combined production traffic of all environments. + +### Example blue-green deployment + +A blue-green deployment strategy uses two environments: one environment (blue) serves the schema variant for live traffic, while the other environment (green) uses a variant for a new release that's under development. When the new release is ready, traffic is migrated from the blue to the green environment. This cycle repeats with each new release. + +As an example, follow these steps to deploy with a supergraph schema of a new release (green) environment: + +1. Publish all subgraphs of a release at once by using the Platform API [`publishSubgraphs`](https://studio.apollographql.com/graph/apollo-platform/variant/main/schema/reference/objects/GraphMutation#publishSubgraphs). + + ```graphql + ## Publish multiple subgraphs together in a batch + ## and retrieve the associated launch, along with any downstream launches. + mutation PublishSubgraphsMutation( + $graphId: ID! + $graphVariant: String! + $revision: String! + $subgraphInputs: [PublishSubgraphsSubgraphInput!]! + ) { + graph(id: $graphId) { + publishSubgraphs( #highlight-line + graphVariant: $graphVariant + revision: $revision + subgraphInputs: $subgraphInputs + ) { + launch { + id + downstreamLaunches { + id + } + } + } + } + } + ``` + + This initiates a launch as well as downstream launches, and it returns the IDs for the launch and any downstream launches. + +1. Poll for the completed launch and any downstream launches. + + ```graphql + ## Poll for the status of any individual launch by ID + query PollLaunchStatusQuery($graphId: ID!, $name: String!, $launchId: ID!) { + graph(id: $graphId) { + variant(name: $name) { + launch(id: $launchId) { + status + } + } + } + } + + ``` + +1. After the launch and downstream launches have completed, retrieve the supergraph schema of the launch. + + ```graphql + ## Fetch the supergraph SDL by launch ID. + query FetchSupergraphSDLQuery($graphId: ID!, $launchId: String!) { + graph(id: $graphId) { + variant(name: $name) { + launch(id: $launchId) { + build { + result { + ... on BuildSuccess { + coreSchema { + coreDocument + } + } + } + } + } + } + } + } + + ``` + +1. Deploy your routers with the `-s` option specifying the supergraph schema. + +### Example canary deployment + +A canary deployment applies graph updates to a small subset of your deployment environment before rolling it out for your entire environment. To configure a canary deployment, you might maintain two production graph variants in Apollo Studio, one named `prod` and the other named `prod-canary`. To deploy a change to a subgraph named `launches`, you might perform the following steps: diff --git a/docs/source/managed-federation/setup.mdx b/docs/source/managed-federation/setup.mdx index b24c65108..180c6b1fd 100644 --- a/docs/source/managed-federation/setup.mdx +++ b/docs/source/managed-federation/setup.mdx @@ -16,8 +16,6 @@ First, complete the **Set up Apollo tools** step from [this tutorial](/graphos/q - Creating a graph in Studio - Installing and authenticating the Rover CLI -Then return here. - ## 2. Publish all subgraph schemas In a supergraph architecture, each of your [subgraphs](../building-supergraphs/subgraphs-overview/) uses the Rover CLI to publish its schema to GraphOS: @@ -71,7 +69,7 @@ const gateway = new ApolloGateway({ This option is specific to _non_-managed federation, in which supergraph schema composition is performed via the Rover CLI. -With managed federation, composition is instead performed by _GraphOS_, and the gateway regularly polls for an updated schema. This enables you to add, remove, and modify your subgraphs _without_ needing to restart your gateway. +With managed federation, composition can instead be performed by _GraphOS_, where the gateway regularly polls for an updated schema. This enables you to add, remove, and modify your subgraphs _without_ needing to restart your gateway. Remove the `supergraphSdl` argument from your `ApolloGateway` constructor entirely: @@ -79,25 +77,29 @@ Remove the `supergraphSdl` argument from your `ApolloGateway` constructor entire const gateway = new ApolloGateway(); ``` -> When running your gateway in an environment where outbound traffic to the internet is restricted, consult the [directions for configuring a proxy](/apollo-server/security/proxy-configuration) within Apollo Server. +When running your gateway in an environment where outbound traffic to the internet is restricted, consult the [directions for configuring a proxy](/apollo-server/security/proxy-configuration) within Apollo Server. -If you've already set up Apollo Federation _without_ connecting your router to GraphOS, you're probably passing the `--supergraph` (or `-s`) option to the Apollo Router's startup command: +If you've already set up Apollo Federation _without_ connecting your router to GraphOS, you're probably passing the [`--supergraph` (or `-s`) option](/router/configuration/overview/#-s----supergraph) to the Apollo Router's startup command: ```sh ./router --config ./router.yaml --supergraph ./your-local-supergraph.graphql ``` -The `--supergraph` option is specific to _non_-managed federation, in which supergraph schema composition is performed via the Rover CLI and provided via a file path. +The `--supergraph` option applies in scenarios where the supergraph schema for the router isn't retrieved by polling Apollo Uplink: + +* For enabling different production environments (such as blue-green deployments) to refer to a single graph variant, the supergraph schema for each production environment is composed via GraphOS and calling Platform APIs, then retrieved from GraphOS and saved, so that its file path can be specified when deploying the router within the corresponding environment. + +* For fully unmanaged federation, the Rover CLI composes the supergraph schema, and the file path of the schema is passed to the router. -_Remove_ the `--supergraph` option (but leave `--config` if it's present): +For other scenarios where the supergraph schema is gotten from Apollo Uplink, _remove_ the `--supergraph` option (but leave `--config` if it's present): ```sh ./router --config ./router.yaml ``` -> With managed federation, composition is instead performed by _GraphOS_, and the router regularly polls for an updated schema. This enables you to add, remove, and modify your subgraphs _without_ needing to restart your router. +> With managed federation, composition can be performed by _GraphOS_, and the router regularly polls for an updated schema from Apollo Uplink. This enables you to add, remove, and modify your subgraphs _without_ needing to restart your router. ## 4. Connect your router to GraphOS From 51fe7220a488beb7748dca36dbc777f5e72d1c3b Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Thu, 9 Nov 2023 17:34:26 -0700 Subject: [PATCH 07/42] Edit benefits --- docs/source/index.mdx | 63 +++++++++++++++---------------------------- 1 file changed, 22 insertions(+), 41 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 7a707df5c..93c8a103b 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -1,15 +1,16 @@ --- title: Introduction to Apollo Federation subtitle: Learn how to combine your GraphQL APIs into a unified supergraph -description: Learn how Apollo Federation can help you combine your GraphQL APIs into a unified, federated supergraph +description: Learn how Apollo Federation can help you combine your GraphQL APIs into a unified, federated supergraph using microservices architecture --- ## What is Apollo Federation? -**Apollo Federation** is an open standard to combine multiple GraphQL APIs. -In a federated architecture, your individual GraphQL APIs are called **subgraphs**, and they're combined into a **supergraph**. +**Apollo Federation** is an open standard for managing GraphQL APIs across any number of services and teams. Federation allows you to combine multiple GraphQL APIs into a single federated graph called a **supergraph**. In a supergraph, the individual GraphQL APIs are called **subgraphs**. -Different subgraphs in the same supergraph can use different server libraries, as long as they are [federation-compatible](./building-supergraphs/supported-subgraphs/). This includes Apollo Server using special extensions from the [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph) library. +### More about subgraphs + +Different subgraphs in the same supergraph can use different server libraries as long as they are [federation-compatible](./building-supergraphs/supported-subgraphs/). This includes Apollo Server using special extensions from the [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph) library. @@ -49,9 +50,7 @@ Learn more about [your router options](./building-supergraphs/router). ## Benefits of federation -As a GraphQL-native microservices architecture, Apollo Federation draws on both paradigms' benefits. -Federated architecture imparts some unique additional benefits by combining GraphQL and microservices frameworks. -Continue reading to learn more. +Apollo Federation offers all the benefits of GraphQL and a [microservices architecture](https://www.atlassian.com/microservices/microservices-architecture/microservices-vs-monolith). Understanding these concepts can help you get the most out of federation. @@ -60,9 +59,11 @@ Continue reading to learn more. -### Challenges of separate services +Beyond the generic benefits of using GraphQL and microservices architecture, Apollo Federation offers the following additional benefits. + +### Preserved client performance -Sometimes, when an organization adopts GraphQL, multiple teams do so independently. Each team sets up a GraphQL services that provides the data used by that team. For example, a travel app may have separate GraphQL servicess for users, flights, and hotels: +Sometimes, when an organization adopts GraphQL, multiple teams do so independently. Each team sets up a GraphQL service that provides the data used by that team. For example, a travel app may have separate GraphQL services for users, flights, and hotels: ```mermaid graph RL; @@ -89,32 +90,7 @@ graph RL; class clients secondary; ``` -But with an architecture like this, a client might need to communicate with _multiple_ APIs to fetch all the data it needs. This diminishes a powerful advantage of GraphQL over traditional REST APIs. - -To counter this, some organizations "stitch" schemas together. Schema stitching links types across services and provides the client with one endpoint to query. The ever-growing complexity of schema stitching can be [challenging to manage](https://www.apollographql.com/blog/announcement/expedia-improved-performance-by-moving-from-schema-stitching-to-apollo-federation/) though. - -### Challenges of monoliths - -Alternatively, some organizations adopting GraphQL may start with a monolithic GraphQL server, allowing clients to fetch all necessary data with one request. - -```mermaid -flowchart LR; - databaseA[(Users
data)]; - databaseB[(Flights
data)]; - databaseC[(Hotels
data)]; - server(["Monolithic
GraphQL server"]); - server --- databaseA & databaseB & databaseC; - clients(Clients); - clients -.- server - class clients secondary; - class teamA,teamB,teamC tertiary; -``` - -Representing an entire enterprise-scale graph as a monolith has its own challenges. Performance might degrade as your users and features increase. Developer productivity can lag due to the coordination challenges of different teams committing changes to the same application. - -### A non-monolithic unifed graph - -With a [unified supergraph](https://principledgraphql.com/integrity), you can reduce performance and productivity bottlenecks, without the additional complexity of schema stitching. Each team can own and develop their subgraph(s) independently because your supergraph's router serves primarily to route incoming operations, not to resolve each of them completely. This allows clients to fetch data from all subgraphs with a single query without the drawbacks of monolithic architecture or schema stitching. +But if you expose multiple GraphQL APIs to clients, a client might need to communicate with _multiple_ APIs to fetch all the data it needs. With a single supergraph, you preserve one of the most powerful features of GraphQL: the ability to fetch all the data you need in a single request. ```mermaid graph LR; @@ -136,14 +112,19 @@ graph LR; class clients secondary; ``` -#### Incremental adoption +This is possible because the supergraph's router serves primarily to route incoming operations, not to resolve each of them completely. + +### Design the schema you want + +Some alternative approaches to combining GraphQL APIs impose limits on your schema, like adding namespaces or representing relationships with IDs instead of types. With these approaches, your subgraph schemas may look unchanged—but the resulting federated schema that clients interact with is more complex. Subsequently, it requires you to make frontend as well as backend changes. + +With Apollo Federation, clients can interact with the composed supergraph schema as if it were a monolith. Consumers of your API shouldn't know or care that it's implemented as microservices. -As with the rest of the Apollo platform, you can (and should) adopt Apollo Federation **incrementally**: +### Maintain a single API -* If you currently use a different federated architecture (such as schema stitching), you can [add federation support to your existing services one at a time](./migrating-from-stitching/). -* If you currently use a monolithic GraphQL server, you can break its functionality out one subgraph at a time. +With federation, every team maintaining a subgraph contributes directly to the overall supergraph schema. Instead of every team needing to manage its own graph layer, each team can be responsible for its slice of the API. When your entire organization contributes to the same graph, each team doesn't need to worry about maintaining its unique API. -In both cases, all your clients continue to work throughout your incremental adoption. +In this structure, the "graph team" might be a separate team that's dedicated to maintaining your router as part of backend infrastructure, or it might be a "meta team" that includes representatives from other teams that maintain subgraphs. ## Next steps @@ -157,7 +138,7 @@ Depending on your goals, you have several options for learning more about federa - [**Performance** considerations](./performance/caching) - [**Debugging and metrics**](./errors) - [Subgraph specifications](./building-supergraphs/router) for federation-compatibility -- A [migration guide from Federation 1 to Federation 2](/federation-2/moving-to-federation-2) +- A [migration guide from Federation 1 to Federation 2](./federation-2/moving-to-federation-2) ### Additional resources From 784f3d6755d3ff5a70bc57bb425e2ab83078e605 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Thu, 9 Nov 2023 17:45:29 -0700 Subject: [PATCH 08/42] Typo --- docs/source/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 93c8a103b..a8e58e313 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -61,7 +61,7 @@ Apollo Federation offers all the benefits of GraphQL and a [microservices archit Beyond the generic benefits of using GraphQL and microservices architecture, Apollo Federation offers the following additional benefits. -### Preserved client performance +### Preserve client performance Sometimes, when an organization adopts GraphQL, multiple teams do so independently. Each team sets up a GraphQL service that provides the data used by that team. For example, a travel app may have separate GraphQL services for users, flights, and hotels: From f5d1d37c669f0372db666ff0e05782ab1ced9216 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Thu, 9 Nov 2023 22:48:39 -0800 Subject: [PATCH 09/42] Update content for uplink, setup, overview --- docs/source/managed-federation/overview.mdx | 7 +++++-- docs/source/managed-federation/setup.mdx | 6 +++--- docs/source/managed-federation/uplink.mdx | 18 ++++++++++++++++-- 3 files changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/source/managed-federation/overview.mdx b/docs/source/managed-federation/overview.mdx index f799c1d56..3635412e2 100644 --- a/docs/source/managed-federation/overview.mdx +++ b/docs/source/managed-federation/overview.mdx @@ -1,12 +1,15 @@ --- title: Managed federation overview +description: Let Apollo GraphOS manage validating and composing your subgraph schemas into a federated, supergraph schema and configuration for your routers. --- [Apollo GraphOS](/graphos/) provides **managed federation** support for graphs that use Apollo Federation. -With managed federation, your subgraphs each publish their schemas to GraphOS, which verifies that they successfully [compose](../federated-types/composition/) into a supergraph schema. +With managed federation, you maintain subgraphs and routers while delegating GraphOS to manage the validation, composition, and update of your supergraph: -On composition success, GraphOS updates your supergraph's latest configuration, which is available at a special endpoint (called the **uplink**) that your router regularly polls for updates: +* Your subgraphs publish their schemas to GraphOS, which stores them in its schema registry, and GraphOS first [validates](./federated-schema-checks) them and then [composes](../federated-types/composition/) them into a supergraph schema. + +* Your routers can poll GraphOS—specifically, its [Apollo Uplink](./uplink) endpoint—to get the latest validated supergraph schema and other configuration. ```mermaid graph LR; diff --git a/docs/source/managed-federation/setup.mdx b/docs/source/managed-federation/setup.mdx index 180c6b1fd..f3293fccc 100644 --- a/docs/source/managed-federation/setup.mdx +++ b/docs/source/managed-federation/setup.mdx @@ -89,7 +89,7 @@ If you've already set up Apollo Federation _without_ connecting your router to G The `--supergraph` option applies in scenarios where the supergraph schema for the router isn't retrieved by polling Apollo Uplink: -* For enabling different production environments (such as blue-green deployments) to refer to a single graph variant, the supergraph schema for each production environment is composed via GraphOS and calling Platform APIs, then retrieved from GraphOS and saved, so that its file path can be specified when deploying the router within the corresponding environment. +* For enabling different production environments (such as blue-green deployments) to refer to a single graph variant, the supergraph schema for each production environment can be composed and retrieved by a workflow using Platform APIs, so that the routers of each environment use the supergraph schema corresponding to the environment. * For fully unmanaged federation, the Rover CLI composes the supergraph schema, and the file path of the schema is passed to the router. @@ -99,7 +99,7 @@ For other scenarios where the supergraph schema is gotten from Apollo Uplink, _r ./router --config ./router.yaml ``` -> With managed federation, composition can be performed by _GraphOS_, and the router regularly polls for an updated schema from Apollo Uplink. This enables you to add, remove, and modify your subgraphs _without_ needing to restart your router. +With managed federation, composition can be performed by _GraphOS_, and the router regularly polls for an updated schema from Apollo Uplink. This enables you to add, remove, and modify your subgraphs _without_ needing to restart your router. ## 4. Connect your router to GraphOS @@ -116,4 +116,4 @@ After obtaining your graph API key, you set the following environment variables ## 5. Deploy the modified router -You can now deploy your modified router, which will fetch its supergraph schema from GraphOS on startup. It can then begin executing operations across your subgraphs. +You can now deploy your modified router, which can either fetch its supergraph schema from GraphOS on startup or specify its supergraph schema for deployment in a particular environment. It can then begin executing operations across your subgraphs. diff --git a/docs/source/managed-federation/uplink.mdx b/docs/source/managed-federation/uplink.mdx index 5ed0e84ca..8cc046535 100644 --- a/docs/source/managed-federation/uplink.mdx +++ b/docs/source/managed-federation/uplink.mdx @@ -3,7 +3,7 @@ title: Apollo Uplink description: Fetch your managed router's configuration --- -When using [managed federation](./overview/), your supergraph's router regularly polls an endpoint called **Apollo Uplink** for its latest supergraph schema and other configuration: +When using [managed federation](./overview/), your supergraph's router by default regularly polls an endpoint called **Apollo Uplink** for its latest supergraph schema and other configuration: ```mermaid graph LR; @@ -23,7 +23,7 @@ graph LR; class uplink secondary; ``` -> Uplink also serves your router's **entitlement** if you're using [Enterprise features](/router/enterprise-features/). +If you're using [Enterprise features](/router/enterprise-features/), Uplink also serves your router's [**license**](/router/enterprise-features/#the-enterprise-license). To maximize uptime, Uplink is hosted simultaneously at _two_ endpoints, one in GCP and one in AWS: @@ -141,3 +141,17 @@ APOLLO_SCHEMA_CONFIG_DELIVERY_ENDPOINT=https://aws.uplink.api.apollographql.com/ Supergraph schemas provided by Uplink cannot exceed 6MB in size. The _vast_ majority of supergraph schemas are well below this limit. If your supergraph schema _does_ exceed 6MB, you can set up a [build status webhook](/graphos/metrics/notifications/build-status-notification/) for your graph. Whenever you're notified of a successful supergraph schema composition, your webhook can fetch the latest supergraph schema [via the Rover CLI](/rover/commands/supergraphs#supergraph-fetch). + +## Bypassing Uplink + +In advanced use cases, you may want your router to use a supergraph schema different than the latest validated schema provided by Uplink. For example, you have different deployment environments for the same [graph variant](/graphos/graphs/#variants), and you want everything that managed federation provides except for your routers to use supergraph schemas specific to their deployment environment. + +For this scenario, you can follow a workflow that, instead of retrieving supergraph schemas from Uplink, uses the [GraphOS Platform API](/graphos/platform-api) to retrieve a supergraph schema for a specific [GraphOS launch](/graphos/delivery/launches). The workflow, in summary: + +1. When deploying your graphs, publish your subgraphs in a batch using a GraphOS Platform API. + * The Platform API triggers a launch (and possible downstream launches for contracts) and returns the launch ID (and downstream launch IDs, if necessary). +1. Poll for the launch status, until the launch (and all downstream launches) has completed successfully. +1. Retrieve the supergraph schema of the successful launch by calling the Platform API with the launch ID. +1. Set or "pin" the supergraph schema to your routers by deploying them with the [`--supergraph` or `-s` option](/router/configuration/overview/#-s----supergraph). + +For an example with operations calling the Platform API, see a [blue-green deployment example](./deployment/#example-blue-green-deployment). From 69bd95a3f802dc53299f9a62070bcedba67055be Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Fri, 10 Nov 2023 15:17:07 -0800 Subject: [PATCH 10/42] link to docker example --- docs/source/managed-federation/deployment.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index abe1d1e75..99466378e 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -200,7 +200,9 @@ As an example, follow these steps to deploy with a supergraph schema of a new re ``` -1. Deploy your routers with the `-s` option specifying the supergraph schema. +1. Deploy your routers with the [`-s` or `--supergraph` option](/router/configuration/overview/#-s----supergraph) to specify the supergraph schema. + + * For an example using the option in a `docker run` command, see [Specifying the supergraph](/router/containerization/docker/#specifying-the-supergraph). ### Example canary deployment From fe525a210e4a0d3ce67aaa3a3d09c3f3bdbe1a5d Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Sat, 11 Nov 2023 13:23:44 +0000 Subject: [PATCH 11/42] chore(deps): update all non-major dependencies (#2851) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- package-lock.json | 32 ++++++++++++++++---------------- package.json | 8 ++++---- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/package-lock.json b/package-lock.json index 0b61938fa..d1c988852 100644 --- a/package-lock.json +++ b/package-lock.json @@ -31,14 +31,14 @@ "@types/async-retry": "1.4.8", "@types/bunyan": "1.8.11", "@types/deep-equal": "1.0.4", - "@types/jest": "29.5.7", - "@types/js-levenshtein": "1.1.2", + "@types/jest": "29.5.8", + "@types/js-levenshtein": "1.1.3", "@types/loglevel": "1.5.4", "@types/make-fetch-happen": "10.0.2", "@types/nock": "10.0.3", "@types/node": "14.18.63", - "@types/node-fetch": "2.6.8", - "@types/uuid": "9.0.6", + "@types/node-fetch": "2.6.9", + "@types/uuid": "9.0.7", "@typescript-eslint/eslint-plugin": "5.62.0", "bunyan": "1.8.15", "codecov": "3.8.3", @@ -3967,9 +3967,9 @@ } }, "node_modules/@types/jest": { - "version": "29.5.7", - "resolved": "https://registry.npmjs.org/@types/jest/-/jest-29.5.7.tgz", - "integrity": "sha512-HLyetab6KVPSiF+7pFcUyMeLsx25LDNDemw9mGsJBkai/oouwrjTycocSDYopMEwFhN2Y4s9oPyOCZNofgSt2g==", + "version": "29.5.8", + "resolved": "https://registry.npmjs.org/@types/jest/-/jest-29.5.8.tgz", + "integrity": "sha512-fXEFTxMV2Co8ZF5aYFJv+YeA08RTYJfhtN5c9JSv/mFEMe+xxjufCb+PHL+bJcMs/ebPUsBu+UNTEz+ydXrR6g==", "dev": true, "dependencies": { "expect": "^29.0.0", @@ -3977,9 +3977,9 @@ } }, "node_modules/@types/js-levenshtein": { - "version": "1.1.2", - "resolved": "https://registry.npmjs.org/@types/js-levenshtein/-/js-levenshtein-1.1.2.tgz", - "integrity": "sha512-/NCbMABw2uacuyE16Iwka1EzREDD50/W2ggRBad0y1WHBvAkvR9OEINxModVY7D428gXBe0igeVX7bUc9GaslQ==", + "version": "1.1.3", + "resolved": "https://registry.npmjs.org/@types/js-levenshtein/-/js-levenshtein-1.1.3.tgz", + "integrity": "sha512-jd+Q+sD20Qfu9e2aEXogiO3vpOC1PYJOUdyN9gvs4Qrvkg4wF43L5OhqrPeokdv8TL0/mXoYfpkcoGZMNN2pkQ==", "dev": true }, "node_modules/@types/js-yaml": { @@ -4047,9 +4047,9 @@ "integrity": "sha512-fAtCfv4jJg+ExtXhvCkCqUKZ+4ok/JQk01qDKhL5BDDoS3AxKXhV5/MAVUZyQnSEd2GT92fkgZl0pz0Q0AzcIQ==" }, "node_modules/@types/node-fetch": { - "version": "2.6.8", - "resolved": "https://registry.npmjs.org/@types/node-fetch/-/node-fetch-2.6.8.tgz", - "integrity": "sha512-nnH5lV9QCMPsbEVdTb5Y+F3GQxLSw1xQgIydrb2gSfEavRPs50FnMr+KUaa+LoPSqibm2N+ZZxH7lavZlAT4GA==", + "version": "2.6.9", + "resolved": "https://registry.npmjs.org/@types/node-fetch/-/node-fetch-2.6.9.tgz", + "integrity": "sha512-bQVlnMLFJ2d35DkPNjEPmd9ueO/rh5EiaZt2bhqiSarPjZIuIV6bPQVqcrEyvNo+AfTrRGVazle1tl597w3gfA==", "dependencies": { "@types/node": "*", "form-data": "^4.0.0" @@ -4132,9 +4132,9 @@ "license": "MIT" }, "node_modules/@types/uuid": { - "version": "9.0.6", - "resolved": "https://registry.npmjs.org/@types/uuid/-/uuid-9.0.6.tgz", - "integrity": "sha512-BT2Krtx4xaO6iwzwMFUYvWBWkV2pr37zD68Vmp1CDV196MzczBRxuEpD6Pr395HAgebC/co7hOphs53r8V7jew==" + "version": "9.0.7", + "resolved": "https://registry.npmjs.org/@types/uuid/-/uuid-9.0.7.tgz", + "integrity": "sha512-WUtIVRUZ9i5dYXefDEAI7sh9/O7jGvHg7Df/5O/gtH3Yabe5odI3UWopVR1qbPXQtvOxWu3mM4XxlYeZtMWF4g==" }, "node_modules/@types/ws": { "version": "8.5.4", diff --git a/package.json b/package.json index 81a94c889..c2dc536d2 100644 --- a/package.json +++ b/package.json @@ -63,14 +63,14 @@ "@types/async-retry": "1.4.8", "@types/bunyan": "1.8.11", "@types/deep-equal": "1.0.4", - "@types/jest": "29.5.7", - "@types/js-levenshtein": "1.1.2", + "@types/jest": "29.5.8", + "@types/js-levenshtein": "1.1.3", "@types/loglevel": "1.5.4", "@types/make-fetch-happen": "10.0.2", "@types/nock": "10.0.3", "@types/node": "14.18.63", - "@types/node-fetch": "2.6.8", - "@types/uuid": "9.0.6", + "@types/node-fetch": "2.6.9", + "@types/uuid": "9.0.7", "@typescript-eslint/eslint-plugin": "5.62.0", "bunyan": "1.8.15", "codecov": "3.8.3", From ba3901d4e07222eaad04613e2161fe07badbdce7 Mon Sep 17 00:00:00 2001 From: "renovate[bot]" <29139614+renovate[bot]@users.noreply.github.com> Date: Mon, 13 Nov 2023 06:22:48 +0000 Subject: [PATCH 12/42] chore(deps): update dependency prettier to v3.1.0 (#2856) Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com> --- package-lock.json | 8 ++++---- package.json | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/package-lock.json b/package-lock.json index d1c988852..282477050 100644 --- a/package-lock.json +++ b/package-lock.json @@ -54,7 +54,7 @@ "mocked-env": "1.3.5", "nock": "13.3.8", "node-fetch": "2.7.0", - "prettier": "3.0.3", + "prettier": "3.1.0", "prettier-2": "npm:prettier@2.8.8", "semver": "7.5.4", "strip-indent": "3.0.0", @@ -14438,9 +14438,9 @@ } }, "node_modules/prettier": { - "version": "3.0.3", - "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.0.3.tgz", - "integrity": "sha512-L/4pUDMxcNa8R/EthV08Zt42WBO4h1rarVtK0K+QJG0X187OLo7l699jWw0GKuwzkPQ//jMFA/8Xm6Fh3J/DAg==", + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.1.0.tgz", + "integrity": "sha512-TQLvXjq5IAibjh8EpBIkNKxO749UEWABoiIZehEPiY4GNpVdhaFKqSTu+QrlU6D2dPAfubRmtJTi4K4YkQ5eXw==", "dev": true, "bin": { "prettier": "bin/prettier.cjs" diff --git a/package.json b/package.json index c2dc536d2..c211080e4 100644 --- a/package.json +++ b/package.json @@ -86,7 +86,7 @@ "mocked-env": "1.3.5", "nock": "13.3.8", "node-fetch": "2.7.0", - "prettier": "3.0.3", + "prettier": "3.1.0", "prettier-2": "npm:prettier@2.8.8", "semver": "7.5.4", "strip-indent": "3.0.0", From d91f297087cb0221cfb0a4c12cf0a4a529a287bc Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Sun, 12 Nov 2023 22:48:07 -0800 Subject: [PATCH 13/42] update subgraph publish lifecycle doc --- docs/source/managed-federation/deployment.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index 99466378e..24161cc9b 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -307,9 +307,11 @@ Because your graph is dynamically changing and multiple subgraphs might be updat 4. If composition fails, the command exits and emits errors. 5. If composition succeeds, Apollo Uplink begins serving the updated supergraph schema. -On the other side of the equation sits the router. The router regularly polls Apollo Uplink for changes to its configuration. The lifecycle of dynamic configuration updates is as follows: +On the other side of the equation sits the router. The router can regularly poll Apollo Uplink for changes to its configuration. The lifecycle of dynamic configuration updates is as follows: 1. The router polls for updates to its configuration. 2. On update, the router downloads the updated configuration, including the new supergraph schema. 3. The router uses the new supergraph schema to update its query planning logic. 4. The router continues to resolve in-flight requests with the previous configuration, while using the updated configuration for all new requests. + +Alternatively, instead of getting its configuration from Apollo Uplink, the router can specify a path to a supergraph schema upon its deployment. This static configuration is useful when you want the router to use a schema different than the latest validated schema from Uplink, or when you don't have connectivity to Apollo Uplink. For an example of this workflow, see an [example of configuring the router for blue-green deployment](#example-blue-green-deployment). From fa3bfaf975f697d403c0a1e9c5081c13a3a38c54 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Mon, 13 Nov 2023 12:28:43 -0800 Subject: [PATCH 14/42] address review comment, add downstreamLaunchInitiation --- docs/source/managed-federation/deployment.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index 24161cc9b..9db877c13 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -134,7 +134,7 @@ As an example, follow these steps to deploy with a supergraph schema of a new re ```graphql ## Publish multiple subgraphs together in a batch - ## and retrieve the associated launch, along with any downstream launches. + ## and retrieve the associated launch, along with any downstream launches synchronously. mutation PublishSubgraphsMutation( $graphId: ID! $graphVariant: String! @@ -146,6 +146,7 @@ As an example, follow these steps to deploy with a supergraph schema of a new re graphVariant: $graphVariant revision: $revision subgraphInputs: $subgraphInputs + downstreamLaunchInitiation: "SYNC" ) { launch { id @@ -158,7 +159,7 @@ As an example, follow these steps to deploy with a supergraph schema of a new re } ``` - This initiates a launch as well as downstream launches, and it returns the IDs for the launch and any downstream launches. + This initiates a launch, as well as any downstream launches necessary for [contracts](graphos/delivery/contracts/#automatic-updates). It returns the launch IDs, with downstream launch IDs configured to return synchronously (`downstreamLaunchInitiation: "SYNC"`) with the mutation. 1. Poll for the completed launch and any downstream launches. From b5ff52ef7021146b6ba940cdfe5bc14ca6af4345 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Mon, 13 Nov 2023 13:56:31 -0800 Subject: [PATCH 15/42] address review comment, use graphVariant input arg --- docs/source/managed-federation/deployment.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index 9db877c13..33f85ea75 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -165,9 +165,9 @@ As an example, follow these steps to deploy with a supergraph schema of a new re ```graphql ## Poll for the status of any individual launch by ID - query PollLaunchStatusQuery($graphId: ID!, $name: String!, $launchId: ID!) { + query PollLaunchStatusQuery($graphId: ID!, $graphVariant: String!, $launchId: ID!) { graph(id: $graphId) { - variant(name: $name) { + variant(name: $graphVariant) { launch(id: $launchId) { status } @@ -181,9 +181,9 @@ As an example, follow these steps to deploy with a supergraph schema of a new re ```graphql ## Fetch the supergraph SDL by launch ID. - query FetchSupergraphSDLQuery($graphId: ID!, $launchId: String!) { + query FetchSupergraphSDLQuery($graphId: ID!, $graphVariant: String!, $launchId: String!) { graph(id: $graphId) { - variant(name: $name) { + variant(name: $graphVariant) { launch(id: $launchId) { build { result { From 6bf3b619e3bffbcf87cc00ce8bf22641639a4ad0 Mon Sep 17 00:00:00 2001 From: Dariusz Kuc <9501705+dariuszkuc@users.noreply.github.com> Date: Mon, 13 Nov 2023 17:32:18 -0600 Subject: [PATCH 16/42] chore: latest compatibility results (#2857) --- .../supported-subgraphs.md | 251 +++++++++--------- 1 file changed, 128 insertions(+), 123 deletions(-) diff --git a/docs/source/building-supergraphs/supported-subgraphs.md b/docs/source/building-supergraphs/supported-subgraphs.md index 32009a51f..bc1e9ce49 100644 --- a/docs/source/building-supergraphs/supported-subgraphs.md +++ b/docs/source/building-supergraphs/supported-subgraphs.md @@ -23,10 +23,10 @@ The following open-source GraphQL server libraries and hosted solutions support Ballerina GraphQL Module -A spec-compliant, production-ready, Standard Library module for building and interacting with GraphQL APIs using Ballerina.

Github: ballerina-platform/module-ballerina-graphql
-Type: Code first
-Stars: 91 ⭐
-Last Release: 2023-09-18

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🔲
@provides🔲
federated tracing🔲
@link🟢
@shareable🔲
@tag🔲
@override🔲
@inaccessible🔲
@composeDirective🔲
@interfaceObject🔲
+A spec-compliant, production-ready, Standard Library module for building and interacting with GraphQL APIs using Ballerina.

Github: ballerina-platform/module-ballerina-graphql
+Type: Code first
+Stars: 145 ⭐
+Last Release: 2023-09-18

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🔲
@provides🔲
federated tracing🔲
@link🟢
@shareable🔲
@tag🔲
@override🔲
@inaccessible🔲
@composeDirective🔲
@interfaceObject🔲
@@ -38,15 +38,15 @@ Last Release: 2023-09-18

- + - +
_service<
GraphQL for .NET
GraphQL for .NET

Github: graphql-dotnet/graphql-dotnet
-Type: Code first | SDL first
-Stars: 5.6k ⭐
-Last Release: 2023-08-11

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🔲
@requires🟢
@provides🟢
federated tracing🔲
@link❌
@shareable🔲
@tag🔲
@override🔲
@inaccessible🔲
@composeDirective🔲
@interfaceObject🔲
GraphQL for .NET

Github: graphql-dotnet/graphql-dotnet
+Type: Code first | SDL first
+Stars: 5.6k ⭐
+Last Release: 2023-08-11

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🔲
@requires🟢
@provides🟢
federated tracing🔲
@link❌
@shareable🔲
@tag🔲
@override🔲
@inaccessible🔲
@composeDirective🔲
@interfaceObject🔲
Hot Chocolate
Open-source GraphQL server for the Microsoft .NET platform that takes the complexity away and lets you focus on delivering the next big thing.

Github: ChilliCream/graphql-platform
-Type: Code first | SDL first
-Stars: 4.7k ⭐
-Last Release: 2023-10-13

Federation Library: apollographql/federation-hotchocolate
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
Open-source GraphQL server for the Microsoft .NET platform that takes the complexity away and lets you focus on delivering the next big thing.

Github: ChilliCream/graphql-platform
+Type: Code first | SDL first
+Stars: 4.7k ⭐
+Last Release: 2023-11-11

Federation Library: apollographql/federation-hotchocolate  Maintained by Apollo
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
@@ -58,10 +58,10 @@ Last Release: 2023-10-13

Federation Library: Absinthe -The GraphQL toolkit for Elixir

Github: absinthe-graphql/absinthe
-Type: Code first
-Stars: 4.2k ⭐
-Last Release: 2021-09-28

Federation Library: DivvyPayHQ/absinthe_federation
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
+The GraphQL toolkit for Elixir

Github: absinthe-graphql/absinthe
+Type: Code first
+Stars: 4.2k ⭐
+Last Release: 2021-09-28

Federation Library: DivvyPayHQ/absinthe_federation
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
@@ -73,15 +73,15 @@ Last Release: 2021-09-28

Federation Library: gqlgen -go generate based graphql server library

Github: 99designs/gqlgen
-Type: SDL first
-Stars: 9.2k ⭐
-Last Release: 2023-10-05

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🔲
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
+go generate based graphql server library

Github: 99designs/gqlgen
+Type: SDL first
+Stars: 9.3k ⭐
+Last Release: 2023-10-24

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🔲
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
GraphQL Go (fork) -This is a fork of graphql-go/graphql that adds Federation support

Github: dariuszkuc/graphql
-Type: Code first
-Stars: 2 ⭐
-Last Release: 2022-11-11

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
+This is a fork of graphql-go/graphql that adds Federation support

Github: dariuszkuc/graphql
+Type: Code first
+Stars: 2 ⭐
+Last Release: 2022-11-11

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
@@ -93,25 +93,25 @@ Last Release: 2022-11-11

- + - + - + - +
_service<
dgs-framework
GraphQL for Java with Spring Boot made easy.

Github: netflix/dgs-framework
-Type: SDL first
-Stars: 2.8k ⭐
-Last Release: 2023-10-12

Core Library: GraphQL Java
Federation Library: apollographql/federation-jvm
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
GraphQL for Java with Spring Boot made easy.

Github: netflix/dgs-framework
+Type: SDL first
+Stars: 2.8k ⭐
+Last Release: 2023-11-06

Core Library: GraphQL Java
Federation Library: apollographql/federation-jvm  Maintained by Apollo
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
GraphQL Java Kickstart (Spring Boot)
GraphQL and GraphiQL Spring Framework Boot Starters - Forked from oembedler/graphql-spring-boot due to inactivity.

Github: graphql-java-kickstart/graphql-spring-boot
-Type: SDL first
-Stars: 1.5k ⭐
-Last Release: 2022-12-05

Core Library: GraphQL Java
Federation Library: apollographql/federation-jvm
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link❌
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
GraphQL and GraphiQL Spring Framework Boot Starters - Forked from oembedler/graphql-spring-boot due to inactivity.

Github: graphql-java-kickstart/graphql-spring-boot
+Type: SDL first
+Stars: 1.5k ⭐
+Last Release: 2022-12-05

Core Library: GraphQL Java
Federation Library: apollographql/federation-jvm  Maintained by Apollo
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link❌
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
GraphQL Kotlin
Libraries for running GraphQL in Kotlin

Github: ExpediaGroup/graphql-kotlin
-Type: Code first
-Stars: 1.7k ⭐
-Last Release: 2023-09-21

Core Library: GraphQL Java
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
Libraries for running GraphQL in Kotlin

Github: ExpediaGroup/graphql-kotlin
+Type: Code first
+Stars: 1.7k ⭐
+Last Release: 2023-10-31

Core Library: GraphQL Java
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
Spring GraphQL
Spring Integration for GraphQL

Github: spring-projects/spring-graphql
-Type: SDL first
-Stars: 1.4k ⭐
-Last Release: 2023-09-19

Core Library: GraphQL Java
Federation Library: apollographql/federation-jvm
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
Spring Integration for GraphQL

Github: spring-projects/spring-graphql
+Type: SDL first
+Stars: 1.4k ⭐
+Last Release: 2023-09-19

Core Library: GraphQL Java
Federation Library: apollographql/federation-jvm  Maintained by Apollo
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
@@ -123,45 +123,45 @@ Last Release: 2023-09-19

Core Library: Apollo Server -🌍  Spec-compliant and production ready JavaScript GraphQL server that lets you develop in a schema-first way. Built for Express, Connect, Hapi, Koa, and more.

Github: apollographql/apollo-server
-Type: SDL first
-Stars: 13.5k ⭐
-Last Release: 2023-10-04

Core Library: GraphQL.js
Federation Library: Apollo Subgraph
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
+🌍  Spec-compliant and production ready JavaScript GraphQL server that lets you develop in a schema-first way. Built for Express, Connect, Hapi, Koa, and more.

Github: apollographql/apollo-server  Maintained by Apollo
+Type: SDL first
+Stars: 13.5k ⭐
+Last Release: 2023-10-26

Core Library: GraphQL.js
Federation Library: Apollo Subgraph  Maintained by Apollo
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
express-graphql -Create a GraphQL HTTP server with Express.

Github: graphql/express-graphql
-Type: SDL first
-Stars: 6.4k ⭐
-Last Release: 2020-11-19

Core Library: GraphQL.js
Federation Library: Apollo Subgraph
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
+Create a GraphQL HTTP server with Express.

Github: graphql/express-graphql
+Type: SDL first
+Stars: 6.4k ⭐
+Last Release: 2020-11-19

Core Library: GraphQL.js
Federation Library: Apollo Subgraph  Maintained by Apollo
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
GraphQL Yoga -The fully-featured GraphQL server with focus on easy setup, performance and great developer experience.

Github: dotansimha/graphql-yoga
-Type: SDL first
-Stars: 7.8k ⭐
-Last Release: 2023-09-28

Core Library: GraphQL.js
Federation Library: Apollo Subgraph
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
+The fully-featured GraphQL server with focus on easy setup, performance and great developer experience.

Github: dotansimha/graphql-yoga
+Type: SDL first
+Stars: 7.8k ⭐
+Last Release: 2023-10-30

Core Library: GraphQL.js
Federation Library: Apollo Subgraph  Maintained by Apollo
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
GraphQL Helix -A highly evolved and framework-agnostic GraphQL HTTP server.

Github: contra/graphql-helix
-Type: SDL first
-Stars: 828 ⭐
-Last Release: 2022-07-09

Core Library: GraphQL.js
Federation Library: Apollo Subgraph
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
+A highly evolved and framework-agnostic GraphQL HTTP server.

Github: contra/graphql-helix
+Type: SDL first
+Stars: 828 ⭐
+Last Release: 2022-07-09

Core Library: GraphQL.js
Federation Library: Apollo Subgraph  Maintained by Apollo
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
Mercurius -Implement GraphQL servers and gateways with Fastify

Github: mercurius-js/mercurius
-Type: SDL first
-Stars: 2.2k ⭐
-Last Release: 2023-07-12

Core Library: GraphQL.js
Federation Library: Apollo Subgraph
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
+Implement GraphQL servers and gateways with Fastify

Github: mercurius-js/mercurius
+Type: SDL first
+Stars: 2.2k ⭐
+Last Release: 2023-10-26

Core Library: GraphQL.js
Federation Library: Apollo Subgraph  Maintained by Apollo
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
NestJS (code first) -A progressive Node.js framework for building efficient, reliable and scalable server-side applications.

Github: nestjs/graphql
-Type: Code first
-Stars: 1.3k ⭐
-Last Release: 2023-06-16

Core Library: GraphQL.js
Federation Library: Apollo Subgraph
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🔲
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🟢
+A progressive Node.js framework for building efficient, reliable and scalable server-side applications.

Github: nestjs/graphql
+Type: Code first
+Stars: 1.4k ⭐
+Last Release: 2023-06-16

Core Library: GraphQL.js
Federation Library: Apollo Subgraph  Maintained by Apollo
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🔲
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🟢
NestJS (SDL First) -A progressive Node.js framework for building efficient, reliable and scalable server-side applications.

Github: nestjs/graphql
-Type: SDL first
-Stars: 1.3k ⭐
-Last Release: 2023-06-16

Core Library: GraphQL.js
Federation Library: Apollo Subgraph
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
+A progressive Node.js framework for building efficient, reliable and scalable server-side applications.

Github: nestjs/graphql
+Type: SDL first
+Stars: 1.4k ⭐
+Last Release: 2023-06-16

Core Library: GraphQL.js
Federation Library: Apollo Subgraph  Maintained by Apollo
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
Pothos GraphQL -Plugin based GraphQL schema builder that makes building graphql schemas with TypeScript easy, fast and enjoyable.

Github: hayes/pothos
-Type: Code first
-Stars: 2.1k ⭐
-Last Release: 2023-10-05

Core Library: GraphQL.js
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
+Plugin based GraphQL schema builder that makes building graphql schemas with TypeScript easy, fast and enjoyable.

Github: hayes/pothos
+Type: Code first
+Stars: 2.1k ⭐
+Last Release: 2023-11-06

Core Library: GraphQL.js
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
@@ -173,15 +173,15 @@ Last Release: 2023-10-05

Core Library: Lighthouse (Laravel) -A framework for serving GraphQL from Laravel

Github: nuwave/lighthouse
-Type: SDL first
-Stars: 3.2k ⭐
-Last Release: 2023-10-06

Core Library: webonyx/graphql-php
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link❌
@shareable🔲
@tag🔲
@override🔲
@inaccessible🔲
@composeDirective🔲
@interfaceObject🔲
+A framework for serving GraphQL from Laravel

Github: nuwave/lighthouse
+Type: SDL first
+Stars: 3.3k ⭐
+Last Release: 2023-10-06

Core Library: webonyx/graphql-php
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link❌
@shareable🔲
@tag🔲
@override🔲
@inaccessible🔲
@composeDirective🔲
@interfaceObject🔲
GraphQL PHP -PHP implementation of the GraphQL specification based on the reference implementation in JavaScript

Github: webonyx/graphql-php
-Type: Code first
-Stars: 4.5k ⭐
-Last Release: 2023-10-04

Federation Library: Skillshare/apollo-federation-php
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link❌
@shareable🔲
@tag🔲
@override🔲
@inaccessible🔲
@composeDirective🔲
@interfaceObject🔲
+PHP implementation of the GraphQL specification based on the reference implementation in JavaScript

Github: webonyx/graphql-php
+Type: Code first
+Stars: 4.6k ⭐
+Last Release: 2023-10-04

Federation Library: Skillshare/apollo-federation-php
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link❌
@shareable🔲
@tag🔲
@override🔲
@inaccessible🔲
@composeDirective🔲
@interfaceObject🔲
@@ -193,20 +193,20 @@ Last Release: 2023-10-04

Federation Library: Ariadne -Python library for implementing GraphQL servers using schema-first approach.

Github: mirumee/ariadne
-Type: SDL first
-Stars: 2.1k ⭐
-Last Release: 2023-06-27

Core Library: GraphQL-core 3
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🟢
+Python library for implementing GraphQL servers using schema-first approach.

Github: mirumee/ariadne
+Type: SDL first
+Stars: 2.1k ⭐
+Last Release: 2023-11-08

Core Library: GraphQL-core 3
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🟢
Graphene -GraphQL framework for Python

Github: graphql-python/graphene
-Type: Code first
-Stars: 7.8k ⭐
-Last Release: 2023-07-26

Core Library: GraphQL-core 3
Federation Library: graphql-python/graphene-federation
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
+GraphQL framework for Python

Github: graphql-python/graphene
+Type: Code first
+Stars: 7.8k ⭐
+Last Release: 2023-07-26

Core Library: GraphQL-core 3
Federation Library: graphql-python/graphene-federation
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
Strawberry -A GraphQL library for Python that leverages type annotations 🍓

Github: strawberry-graphql/strawberry
-Type: Code first
-Stars: 3.5k ⭐
-Last Release: 2023-10-07

Core Library: GraphQL-core 3
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
+A GraphQL library for Python that leverages type annotations 🍓

Github: strawberry-graphql/strawberry
+Type: Code first
+Stars: 3.5k ⭐
+Last Release: 2023-11-08

Core Library: GraphQL-core 3
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
@@ -218,10 +218,10 @@ Last Release: 2023-10-07

Core Library: GraphQL Ruby -Ruby implementation of GraphQL

Github: rmosolgo/graphql-ruby
-Type: Code first
-Stars: 5.3k ⭐
-Last Release: 2021-02-12

Federation Library: Gusto/apollo-federation-ruby
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🟢
+Ruby implementation of GraphQL

Github: rmosolgo/graphql-ruby
+Type: Code first
+Stars: 5.3k ⭐
+Last Release: 2021-02-12

Federation Library: Gusto/apollo-federation-ruby
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🟢
@@ -233,10 +233,10 @@ Last Release: 2021-02-12

Federation Library: async-graphql -A GraphQL server library implemented in Rust

Github: async-graphql/async-graphql
-Type: Code first
-Stars: 3.0k ⭐
-Last Release: 2022-11-28

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
+A GraphQL server library implemented in Rust

Github: async-graphql/async-graphql
+Type: Code first
+Stars: 3.1k ⭐
+Last Release: 2022-11-28

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🔲
@@ -248,15 +248,15 @@ Last Release: 2022-11-28

- + - +
_service<
Caliban
Functional GraphQL library for Scala

Github: ghostdogpr/caliban
-Type: Code first
-Stars: 887 ⭐
-Last Release: 2023-09-10

_service🟢
@key (single)🟢
@key (multi)🔲
@key (composite)🔲
repeatable @key🔲
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
Functional GraphQL library for Scala

Github: ghostdogpr/caliban
+Type: Code first
+Stars: 887 ⭐
+Last Release: 2023-11-09

_service🟢
@key (single)🟢
@key (multi)🔲
@key (composite)🟢
repeatable @key🔲
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
Sangria
Scala GraphQL implementation

Github: sangria-graphql/sangria
-Type: Code first
-Stars: 2.0k ⭐
-Last Release: 2023-09-12

Federation Library: sangria-graphql/sangria-federated
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
Scala GraphQL implementation

Github: sangria-graphql/sangria
+Type: Code first
+Stars: 2.0k ⭐
+Last Release: 2023-10-16

Federation Library: sangria-graphql/sangria-federated
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
@@ -268,10 +268,10 @@ Last Release: 2023-09-12

Federation Library: Graphiti -The Swift GraphQL Schema framework for macOS and Linux

Github: GraphQLSwift/Graphiti
-Type: SDL first
-Stars: 509 ⭐
-Last Release: 2023-07-31

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
+The Swift GraphQL Schema framework for macOS and Linux

Github: GraphQLSwift/Graphiti
+Type: SDL first
+Stars: 510 ⭐
+Last Release: 2023-10-25

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
@@ -283,20 +283,25 @@ Last Release: 2023-07-31

- + - + + + - + - + - +
_service<
AWS AppSync
Serverless GraphQL and Pub/Sub APIs

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
Serverless GraphQL and Pub/Sub APIs

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
Dgraph
Dgraph is the native GraphQL database with a graph backend. It is open-source, scalable, distributed, highly available and lightning fast.

_service❌
@key (single)🟢
@key (multi)🔲
@key (composite)🔲
repeatable @key🔲
@requires🔲
@provides🔲
federated tracing🔲
@link❌
@shareable🔲
@tag🔲
@override🔲
@inaccessible🔲
@composeDirective🔲
@interfaceObject🔲
Dgraph is the native GraphQL database with a graph backend. It is open-source, scalable, distributed, highly available and lightning fast.

_service❌
@key (single)🟢
@key (multi)🔲
@key (composite)🔲
repeatable @key🔲
@requires🔲
@provides🔲
federated tracing🔲
@link❌
@shareable🔲
@tag🔲
@override🔲
@inaccessible🔲
@composeDirective🔲
@interfaceObject🔲
Grafbase
The API platform for developers

Github: grafbase/grafbase
+Type: Code first | SDL first
+Stars: 846 ⭐
+Last Release: 2023-11-11

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🔲
@link❌
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
GraphQL Mesh
Executable GraphQL schema from multiple data sources, query anything, run anywhere.

Github: Urigo/graphql-mesh
-Type: undefined
-Stars: 3.0k ⭐
-Last Release: 2023-10-12

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
Executable GraphQL schema from multiple data sources, query anything, run anywhere.

Github: Urigo/graphql-mesh
+Type: undefined
+Stars: 3.0k ⭐
+Last Release: 2023-11-08

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
Neo4J Graph Database
A GraphQL to Cypher query execution layer for Neo4j and JavaScript GraphQL implementations.

Github: neo4j/graphql
-Type: Code first | SDL first
-Stars: 455 ⭐
-Last Release: 2023-10-12

Core Library: GraphQL.js
Federation Library: Apollo Subgraph
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
A GraphQL to Cypher query execution layer for Neo4j and JavaScript GraphQL implementations.

Github: neo4j/graphql
+Type: Code first | SDL first
+Stars: 454 ⭐
+Last Release: 2023-11-02

Core Library: GraphQL.js
Federation Library: Apollo Subgraph  Maintained by Apollo
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
StepZen, an IBM Company
Build GraphQL APIs for all your data in a declarative way. Federate across any data source, including GraphQL.

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🔲
repeatable @key🔲
@requires🟢
@provides🔲
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
Build GraphQL APIs for all your data in a declarative way. Federate across any data source, including GraphQL.

_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🔲
repeatable @key🔲
@requires🟢
@provides🔲
federated tracing🔲
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
From 438217805aa4e37cf8ba365b23d33a7fdf3fabee Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Mon, 13 Nov 2023 16:43:12 -0700 Subject: [PATCH 17/42] Incorporate SA feedback --- docs/source/index.mdx | 68 +++++++++++++++++++++++++------------------ 1 file changed, 40 insertions(+), 28 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index a8e58e313..a650432eb 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -1,16 +1,16 @@ --- title: Introduction to Apollo Federation subtitle: Learn how to combine your GraphQL APIs into a unified supergraph -description: Learn how Apollo Federation can help you combine your GraphQL APIs into a unified, federated supergraph using microservices architecture +description: Learn how Apollo Federation can help you declaratively combine your GraphQL APIs into a unified, federated supergraph using microservices architecture --- ## What is Apollo Federation? -**Apollo Federation** is an open standard for managing GraphQL APIs across any number of services and teams. Federation allows you to combine multiple GraphQL APIs into a single federated graph called a **supergraph**. In a supergraph, the individual GraphQL APIs are called **subgraphs**. +**Apollo Federation** is an open standard for managing GraphQL APIs across any number of services and teams. Federation lets you combine multiple GraphQL APIs into a single graph called a **supergraph**. In a supergraph, the individual GraphQL APIs are called **subgraphs**. ### More about subgraphs -Different subgraphs in the same supergraph can use different server libraries as long as they are [federation-compatible](./building-supergraphs/supported-subgraphs/). This includes Apollo Server using special extensions from the [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph) library. +Different subgraphs in the same supergraph can use different server languages and libraries as long as they are [federation-compatible](./building-supergraphs/supported-subgraphs/). This includes Apollo Server using extensions from the [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph) library. @@ -20,11 +20,9 @@ Learn more about [choosing subgraph libraries](./building-supergraphs/subgraphs- ### The role of the router -A supergraph consists of more than just subgraphs. It also includes a **router** that acts as an API gateway for your subgraphs. -The router is a separate service that exposes a GraphQL endpoint to external clients. - -Clients can fetch data from all your subgraphs with a single request to the router. The router receives incoming GraphQL operations from clients and intelligently routes them across your subgraphs. The router then receives subgraph responses and returns a single response to the client. - +A supergraph consists of more than just subgraphs. It also includes a **router**. +A router is a separate service that exposes a GraphQL endpoint to external clients. +Clients can fetch data from all your subgraphs with a single request to the router. ```mermaid graph LR; @@ -40,17 +38,19 @@ graph LR; class clients secondary; ``` -Clients only query the router—never subgraphs directly—and only the router queries subgraphs. **For clients, the request and response cycle of querying the router looks exactly the same as querying any other GraphQL server.** No client-side configuration is required. +The router acts as more than just a gateway for your subgraphs. Beyond routing requests to subgraphs, the router intelligently orchestrates them by generating [a query plan](./query-plans/). A query plan is a blueprint for dividing a single incoming operation into one or more operations that are each resolvable by a single subgraph. The router executes the plan, receives subgraph responses, and returns a single response to the client. + +For performance and security reasons, clients should only query the router. And only the router—never clients—should query subgraphs. **For clients, the request and response cycle of querying the router looks exactly the same as querying any other GraphQL server.** No client-side configuration is required. -Learn more about [your router options](./building-supergraphs/router). +- Learn more about [your router options](./building-supergraphs/router). ## Benefits of federation -Apollo Federation offers all the benefits of GraphQL and a [microservices architecture](https://www.atlassian.com/microservices/microservices-architecture/microservices-vs-monolith). Understanding these concepts can help you get the most out of federation. +Apollo Federation lets your API teams operate in a [microservices architecture](https://www.atlassian.com/microservices/microservices-architecture/microservices-vs-monolith) while exposing a unified GraphQL API to clients. Understanding these concepts can help you get the most out of federation. @@ -90,7 +90,7 @@ graph RL; class clients secondary; ``` -But if you expose multiple GraphQL APIs to clients, a client might need to communicate with _multiple_ APIs to fetch all the data it needs. With a single supergraph, you preserve one of the most powerful features of GraphQL: the ability to fetch all the data you need in a single request. +But if you expose multiple GraphQL APIs to clients, a client might need to communicate with _multiple_ APIs to fetch all the data it needs. With a single supergraph, you preserve a powerful advantage of GraphQL over traditional REST APIs: the ability to fetch all the data you need in a single request. ```mermaid graph LR; @@ -112,9 +112,9 @@ graph LR; class clients secondary; ``` -This is possible because the supergraph's router serves primarily to route incoming operations, not to resolve each of them completely. +This is possible because the supergraph's router serves to intelligently route incoming operations, not to resolve each of them completely. -### Design the schema you want +### Design schemas at scale Some alternative approaches to combining GraphQL APIs impose limits on your schema, like adding namespaces or representing relationships with IDs instead of types. With these approaches, your subgraph schemas may look unchanged—but the resulting federated schema that clients interact with is more complex. Subsequently, it requires you to make frontend as well as backend changes. @@ -126,30 +126,42 @@ With federation, every team maintaining a subgraph contributes directly to the o In this structure, the "graph team" might be a separate team that's dedicated to maintaining your router as part of backend infrastructure, or it might be a "meta team" that includes representatives from other teams that maintain subgraphs. -## Next steps +## Additional resources + +Depending on your goals, you have several options for learning more about federation. +If you're new to the concept of federated architecture, this [overview article](https://graphql.com/learn/federated-architecture/) is a helpful place to start. +If you'd like to recap key concepts of Apollo Federation, the video below gives a great overview. + + + + + + + +### Interactive learning + +Apollo offers these resources for interactive learning: + +- The [interactive course](https://www.apollographql.com/tutorials/voyage-part1) is the best way to learn about federation through using it +- If you prefer a less structured learning experience, you can fork and tinker with the [demo app](https://github.com/apollographql/supergraph-demo-fed2) -Depending on your goals, you have several options for learning more about federation. Apollo's docs offer these sections: +### Further documentation + +Apollo's docs offer these sections: - A [Quickstart tutorial](./quickstart/setup/) that walks you through setting up an Apollo Federation supergraph - Details on [subgraphs](./building-supergraphs/subgraphs-overview) and [routers](./building-supergraphs/router) in **Building Your Supergraph** -- A conceptual overview of writing [**Federated Schemas**](./federated-types/) +- A conceptual overview of writing [**Federated Schemas**](./federated-types/overview) - A [guide on using Apollo GraphOS](./managed-federation) to automate and manage deployments of your federated schemas (this is also known as **Managed Federation**) - Reference materials for: - - [**Performance** considerations](./performance/caching) - - [**Debugging and metrics**](./errors) + - [Performance considerations](./performance/caching) + - [Debugging and metrics](./errors) - [Subgraph specifications](./building-supergraphs/router) for federation-compatibility -- A [migration guide from Federation 1 to Federation 2](./federation-2/moving-to-federation-2) - -### Additional resources -Outside of the docs, Apollo offers these resources for learning more about federation: +### Best practices -- A general [overview of federated architecture](https://graphql.com/learn/federated-architecture/) -- An [interactive course](https://www.apollographql.com/tutorials/voyage-part1) focused on Apollo Federation -- A [demo app](https://github.com/apollographql/supergraph-demo-fed2) that you can fork and tinker with -- The [overview video](https://youtu.be/wRExDdgs6JU) embedded below: +The [Supergraph Architecture Framework](https://saf.apollographql.com/) (SAF) is a set of best practices for building a reliable, secure, performant, and developer-friendly graph. You can use the SAF assessment to quantify your graph's current state and identify areas for improvement. - From 9ca5168612698af392294f53209cdfc1db5c92bb Mon Sep 17 00:00:00 2001 From: Dariusz Kuc <9501705+dariuszkuc@users.noreply.github.com> Date: Tue, 14 Nov 2023 13:41:58 -0600 Subject: [PATCH 18/42] chore: sangria compatibility updates (#2858) --- docs/source/building-supergraphs/supported-subgraphs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/building-supergraphs/supported-subgraphs.md b/docs/source/building-supergraphs/supported-subgraphs.md index bc1e9ce49..4202d9745 100644 --- a/docs/source/building-supergraphs/supported-subgraphs.md +++ b/docs/source/building-supergraphs/supported-subgraphs.md @@ -251,12 +251,12 @@ Last Release: 2022-11-28

+Last Release: 2023-11-09

+Last Release: 2023-10-16

Federation Library: sangria-graphql/sangria-federated
_service<
Functional GraphQL library for Scala

Github: ghostdogpr/caliban
Type: Code first
Stars: 887 ⭐
-Last Release: 2023-11-09

_service🟢
@key (single)🟢
@key (multi)🔲
@key (composite)🟢
repeatable @key🔲
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
Sangria
Scala GraphQL implementation

Github: sangria-graphql/sangria
Type: Code first
Stars: 2.0k ⭐
-Last Release: 2023-10-16

Federation Library: sangria-graphql/sangria-federated
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🔲
@interfaceObject🔲
_service🟢
@key (single)🟢
@key (multi)🟢
@key (composite)🟢
repeatable @key🟢
@requires🟢
@provides🟢
federated tracing🟢
@link🟢
@shareable🟢
@tag🟢
@override🟢
@inaccessible🟢
@composeDirective🟢
@interfaceObject🟢
From e9c58e8dc3d788672e8b2bdf8a9f6b4297d76581 Mon Sep 17 00:00:00 2001 From: Edward Huang <18322228+shorgi@users.noreply.github.com> Date: Tue, 14 Nov 2023 12:17:40 -0800 Subject: [PATCH 19/42] Apply suggestions from code review Co-authored-by: Maria Elisabeth Schreiber --- docs/source/managed-federation/deployment.mdx | 8 ++++---- docs/source/managed-federation/overview.mdx | 4 ++-- docs/source/managed-federation/setup.mdx | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index 33f85ea75..1c0c798c4 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -118,11 +118,11 @@ The next time it starts up or polls, your router obtains an updated configuratio ## Using variants to control rollout -Your deployment model may require deploying a specific version of your graph, for example for blue-green deployments or canary deployments. With managed federation, you can control which version of your graph a fleet of routers are using. In the majority of cases, rolling over all of your router instances to a new schema version is safe, assuming you've used [schema checks](./federated-schema-checks/) to confirm that your changes are backward compatible. +Your deployment model may require deploying a specific version of your graph, for example, for blue-green or canary deployments. With managed federation, you can control which version of your graph your router fleet uses. In most cases, rolling over all of your router instances to a new schema version is safe, assuming you've used [schema checks](./federated-schema-checks/) to confirm that your changes are backward compatible. -However, changes at the router level might involve a variety of different updates, such as [migrating entities](../entities-advanced/#migrating-entities-and-fields) from one subgraph to another. If your infrastructure requires a more advanced deployment process, you can use [graph variants](/graphos/graphs/#variants) to manage different fleets of routers running with different configurations. +However, changes at the router level might involve a variety of different updates, such as [migrating entities](../entities-advanced/#migrating-entities-and-fields) from one subgraph to another. If your infrastructure requires a more advanced deployment process, you can use [graph variants](/graphos/graphs/#variants) to manage router fleets running with different configurations. -Specifically, for deployments that run in different production environments, such as blue-green deployments, you can configure your environments to refer to a single graph variant by pinning the supergraph schema of each environment to your routers at deployment time. Using a single variant between different production environments enables Studio to get usage reports and do analysis on the combined production traffic of all environments. +Specifically, for deployments that run in different production environments, such as blue-green deployments, you can configure your environments to refer to a single graph variant by pinning each environment's supergraph schema to your routers at deployment time. Using a single variant between different production environments enables Studio to get usage reports and analyze the combined production traffic of all environments. ### Example blue-green deployment @@ -130,7 +130,7 @@ A blue-green deployment strategy uses two environments: one environment (blue) s As an example, follow these steps to deploy with a supergraph schema of a new release (green) environment: -1. Publish all subgraphs of a release at once by using the Platform API [`publishSubgraphs`](https://studio.apollographql.com/graph/apollo-platform/variant/main/schema/reference/objects/GraphMutation#publishSubgraphs). +1. Publish all the release's subgraphs at once using the Platform API [`publishSubgraphs` mutation](https://studio.apollographql.com/graph/apollo-platform/variant/main/schema/reference/objects/GraphMutation#publishSubgraphs). ```graphql ## Publish multiple subgraphs together in a batch diff --git a/docs/source/managed-federation/overview.mdx b/docs/source/managed-federation/overview.mdx index 3635412e2..ed9cd1412 100644 --- a/docs/source/managed-federation/overview.mdx +++ b/docs/source/managed-federation/overview.mdx @@ -5,9 +5,9 @@ description: Let Apollo GraphOS manage validating and composing your subgraph sc [Apollo GraphOS](/graphos/) provides **managed federation** support for graphs that use Apollo Federation. -With managed federation, you maintain subgraphs and routers while delegating GraphOS to manage the validation, composition, and update of your supergraph: +With managed federation, you maintain subgraphs and delegate GraphOS to manage the validation, composition, and update of your supergraph: -* Your subgraphs publish their schemas to GraphOS, which stores them in its schema registry, and GraphOS first [validates](./federated-schema-checks) them and then [composes](../federated-types/composition/) them into a supergraph schema. +* Your subgraphs publish their schemas to GraphOS, which stores them in its schema registry. GraphOS then [validates](./federated-schema-checks) and [composes](../federated-types/composition/) them into a supergraph schema. * Your routers can poll GraphOS—specifically, its [Apollo Uplink](./uplink) endpoint—to get the latest validated supergraph schema and other configuration. diff --git a/docs/source/managed-federation/setup.mdx b/docs/source/managed-federation/setup.mdx index f3293fccc..ac58f2e72 100644 --- a/docs/source/managed-federation/setup.mdx +++ b/docs/source/managed-federation/setup.mdx @@ -71,7 +71,7 @@ This option is specific to _non_-managed federation, in which supergraph schema With managed federation, composition can instead be performed by _GraphOS_, where the gateway regularly polls for an updated schema. This enables you to add, remove, and modify your subgraphs _without_ needing to restart your gateway. -Remove the `supergraphSdl` argument from your `ApolloGateway` constructor entirely: +To use managed federation, ensure your `ApolloGateway` constructor doesn't include the `supergraphSdl` argument: ```js const gateway = new ApolloGateway(); @@ -87,11 +87,11 @@ If you've already set up Apollo Federation _without_ connecting your router to G ./router --config ./router.yaml --supergraph ./your-local-supergraph.graphql ``` -The `--supergraph` option applies in scenarios where the supergraph schema for the router isn't retrieved by polling Apollo Uplink: +The `--supergraph` option applies in scenarios where the router doesn't retrieve the supergraph schema by polling Apollo Uplink. These include: * For enabling different production environments (such as blue-green deployments) to refer to a single graph variant, the supergraph schema for each production environment can be composed and retrieved by a workflow using Platform APIs, so that the routers of each environment use the supergraph schema corresponding to the environment. -* For fully unmanaged federation, the Rover CLI composes the supergraph schema, and the file path of the schema is passed to the router. +* **Unmanaged federation**: The Rover CLI composes the supergraph schema and passes the schema's file path to the router via the `--supergraph` option. For other scenarios where the supergraph schema is gotten from Apollo Uplink, _remove_ the `--supergraph` option (but leave `--config` if it's present): From 4d94b643853e27cb7a5f7a3fbfdcb5c3acf17fc3 Mon Sep 17 00:00:00 2001 From: Edward Huang <18322228+shorgi@users.noreply.github.com> Date: Tue, 14 Nov 2023 12:34:34 -0800 Subject: [PATCH 20/42] Apply suggestions from code review Co-authored-by: Maria Elisabeth Schreiber --- docs/source/managed-federation/deployment.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index 1c0c798c4..2db78a79a 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -159,7 +159,7 @@ As an example, follow these steps to deploy with a supergraph schema of a new re } ``` - This initiates a launch, as well as any downstream launches necessary for [contracts](graphos/delivery/contracts/#automatic-updates). It returns the launch IDs, with downstream launch IDs configured to return synchronously (`downstreamLaunchInitiation: "SYNC"`) with the mutation. + This initiates a [launch](/graphos/delivery/launches/), as well as any downstream launches necessary for [contracts](graphos/delivery/contracts/#automatic-updates). It returns the launch IDs, with downstream launch IDs configured to return synchronously (`downstreamLaunchInitiation: "SYNC"`) with the mutation. 1. Poll for the completed launch and any downstream launches. From 8f8326e97cbb0b482e1c8e420b81442544c84258 Mon Sep 17 00:00:00 2001 From: Edward Huang <18322228+shorgi@users.noreply.github.com> Date: Tue, 14 Nov 2023 14:49:08 -0800 Subject: [PATCH 21/42] Apply suggestions from code review Co-authored-by: Maria Elisabeth Schreiber --- docs/source/managed-federation/overview.mdx | 2 +- docs/source/managed-federation/setup.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/managed-federation/overview.mdx b/docs/source/managed-federation/overview.mdx index ed9cd1412..fafea7d65 100644 --- a/docs/source/managed-federation/overview.mdx +++ b/docs/source/managed-federation/overview.mdx @@ -9,7 +9,7 @@ With managed federation, you maintain subgraphs and delegate GraphOS to manage t * Your subgraphs publish their schemas to GraphOS, which stores them in its schema registry. GraphOS then [validates](./federated-schema-checks) and [composes](../federated-types/composition/) them into a supergraph schema. -* Your routers can poll GraphOS—specifically, its [Apollo Uplink](./uplink) endpoint—to get the latest validated supergraph schema and other configuration. +* Your routers can poll GraphOS—specifically, its [Apollo Uplink](./uplink) endpoint—to get the latest validated supergraph schema and other configurations. ```mermaid graph LR; diff --git a/docs/source/managed-federation/setup.mdx b/docs/source/managed-federation/setup.mdx index ac58f2e72..09a4ac9e3 100644 --- a/docs/source/managed-federation/setup.mdx +++ b/docs/source/managed-federation/setup.mdx @@ -93,7 +93,7 @@ The `--supergraph` option applies in scenarios where the router doesn't retrieve * **Unmanaged federation**: The Rover CLI composes the supergraph schema and passes the schema's file path to the router via the `--supergraph` option. -For other scenarios where the supergraph schema is gotten from Apollo Uplink, _remove_ the `--supergraph` option (but leave `--config` if it's present): +For other scenarios where the router retrieves the supergraph schema from Apollo Uplink, _remove_ the `--supergraph` option (but leave `--config` if it's present): ```sh ./router --config ./router.yaml From 7cf026ba7c6fb51cad35a2c42b9342c7a448faa6 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Tue, 14 Nov 2023 16:02:00 -0700 Subject: [PATCH 22/42] Incorporate discussion feedback --- docs/source/index.mdx | 119 +++++++++++++++++++++--------------------- 1 file changed, 60 insertions(+), 59 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index a650432eb..1bfb6bf1a 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -6,51 +6,29 @@ description: Learn how Apollo Federation can help you declaratively combine your ## What is Apollo Federation? -**Apollo Federation** is an open standard for managing GraphQL APIs across any number of services and teams. Federation lets you combine multiple GraphQL APIs into a single graph called a **supergraph**. In a supergraph, the individual GraphQL APIs are called **subgraphs**. - -### More about subgraphs - -Different subgraphs in the same supergraph can use different server languages and libraries as long as they are [federation-compatible](./building-supergraphs/supported-subgraphs/). This includes Apollo Server using extensions from the [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph) library. - - - -Learn more about [choosing subgraph libraries](./building-supergraphs/subgraphs-overview#choosing-a-subgraph-library). - - - -### The role of the router - -A supergraph consists of more than just subgraphs. It also includes a **router**. -A router is a separate service that exposes a GraphQL endpoint to external clients. -Clients can fetch data from all your subgraphs with a single request to the router. +**Apollo Federation** lets you combine multiple GraphQL APIs into a unified graph with a single entry point called the **router**. +Clients make requests to the router, which intelligently distributes them across your APIs and returns a unified response. +This architecture enables clients to interact with multiple services with a single request. ```mermaid graph LR; clients(Clients); - subgraph "Supergraph"; router([Router]); - serviceA[Subgraph A]; - serviceB[Subgraph B]; - serviceC[Subgraph C]; + serviceA[GraphQL API
A]; + serviceB[GraphQL API
B]; + serviceC[GraphQL API
C]; router --- serviceA & serviceB & serviceC; - end; clients -.- router; class clients secondary; ``` -The router acts as more than just a gateway for your subgraphs. Beyond routing requests to subgraphs, the router intelligently orchestrates them by generating [a query plan](./query-plans/). A query plan is a blueprint for dividing a single incoming operation into one or more operations that are each resolvable by a single subgraph. The router executes the plan, receives subgraph responses, and returns a single response to the client. - -For performance and security reasons, clients should only query the router. And only the router—never clients—should query subgraphs. **For clients, the request and response cycle of querying the router looks exactly the same as querying any other GraphQL server.** No client-side configuration is required. - - - -- Learn more about [your router options](./building-supergraphs/router). - - +For performance and security reasons, clients should only query the router, and only the router should query the constituent APIs. +For clients, the request and response cycle of querying the router looks the same as querying any GraphQL server. +No client-side configuration is required. ## Benefits of federation -Apollo Federation lets your API teams operate in a [microservices architecture](https://www.atlassian.com/microservices/microservices-architecture/microservices-vs-monolith) while exposing a unified GraphQL API to clients. Understanding these concepts can help you get the most out of federation. +Apollo Federation lets API teams operate in a [microservices architecture](https://www.atlassian.com/microservices/microservices-architecture/microservices-vs-monolith) while exposing a unified GraphQL API to clients. Understanding these concepts can help you get the most out of federation. @@ -90,16 +68,16 @@ graph RL; class clients secondary; ``` -But if you expose multiple GraphQL APIs to clients, a client might need to communicate with _multiple_ APIs to fetch all the data it needs. With a single supergraph, you preserve a powerful advantage of GraphQL over traditional REST APIs: the ability to fetch all the data you need in a single request. +But if you expose multiple GraphQL APIs to clients, a client might need to communicate with _multiple_ APIs to fetch all the data it needs. With a single federated graph, you preserve a powerful advantage of GraphQL over traditional REST APIs: the ability to fetch all the data you need in a single request. ```mermaid graph LR; clients(Clients); - subgraph "Supergraph"; + subgraph supergraph[" "]; router([Router]); - serviceA[Users Subgraph]; - serviceB[Flights Subgraph]; - serviceC[Hotels Subgraph]; + serviceA[Users API]; + serviceB[Flights API]; + serviceC[Hotels API]; databaseA[(Users
data)]; databaseB[(Flights
data)]; databaseC[(Hotels
data)]; @@ -112,47 +90,70 @@ graph LR; class clients secondary; ``` -This is possible because the supergraph's router serves to intelligently route incoming operations, not to resolve each of them completely. +Federation makes this possible because the router serves to orchestrate incoming operations, not to resolve each of them completely. ### Design schemas at scale -Some alternative approaches to combining GraphQL APIs impose limits on your schema, like adding namespaces or representing relationships with IDs instead of types. With these approaches, your subgraph schemas may look unchanged—but the resulting federated schema that clients interact with is more complex. Subsequently, it requires you to make frontend as well as backend changes. +Some alternative approaches to combining GraphQL APIs impose limits on your schema, like adding namespaces or representing relationships with IDs instead of types. With these approaches, your individual GraphQL API schemas may look unchanged—but the resulting federated schema that clients interact with is more complex. Subsequently, it requires you to make frontend as well as backend changes. -With Apollo Federation, clients can interact with the composed supergraph schema as if it were a monolith. Consumers of your API shouldn't know or care that it's implemented as microservices. +With Apollo Federation, clients can interact with the federated schema as if it were a monolith. Consumers of your API shouldn't know or care that it's implemented as microservices. ### Maintain a single API -With federation, every team maintaining a subgraph contributes directly to the overall supergraph schema. Instead of every team needing to manage its own graph layer, each team can be responsible for its slice of the API. When your entire organization contributes to the same graph, each team doesn't need to worry about maintaining its unique API. +With federation, every team maintaining a GraphQL API contributes directly to the overall federated schema. Instead of every team needing to manage its own graph layer, each team can be responsible for its slice of the API. When your entire organization contributes to the same graph, each team doesn't need to worry about maintaining its unique API. -In this structure, the "graph team" might be a separate team that's dedicated to maintaining your router as part of backend infrastructure, or it might be a "meta team" that includes representatives from other teams that maintain subgraphs. +In this structure, the "graph team" might be a separate team dedicated to maintaining your router as part of the backend infrastructure, or it might be a "meta team" that includes representatives from other teams that maintain individual services. -## Additional resources +## Next steps -Depending on your goals, you have several options for learning more about federation. -If you're new to the concept of federated architecture, this [overview article](https://graphql.com/learn/federated-architecture/) is a helpful place to start. -If you'd like to recap key concepts of Apollo Federation, the video below gives a great overview. +Before continuing, it's helpful to know some terminology: + +- When combining multiple GraphQL APIs, the single, federated graph is called a **supergraph**. +- In a supergraph, the individual GraphQL APIs are called **subgraphs**. + +```mermaid +graph LR; + clients(Clients); + router([Router]); + subgraph "Supergraph" + serviceA[Subgraph
A]; + serviceB[Subgraph
B]; + serviceC[Subgraph
C]; + router --- serviceA & serviceB & serviceC; + end + clients -.- router; + class clients secondary; +``` + +Different subgraphs in the same supergraph can use different server languages and libraries as long as they are [federation-compatible](./building-supergraphs/supported-subgraphs/). + + + +- Learn more about [choosing subgraph libraries](./building-supergraphs/subgraphs-overview#choosing-a-subgraph-library). +- Learn more about [your router options](./building-supergraphs/router). + + - +### Additional resources - +Depending on your goals, you have several options for learning more about federation: +- If you're new to federated architecture, this [overview article](https://graphql.com/learn/federated-architecture/) can familiarize the concepts. +- If you'd like to recap key concepts of Apollo Federation, the video below gives a great overview. - + -### Interactive learning + -Apollo offers these resources for interactive learning: + -- The [interactive course](https://www.apollographql.com/tutorials/voyage-part1) is the best way to learn about federation through using it -- If you prefer a less structured learning experience, you can fork and tinker with the [demo app](https://github.com/apollographql/supergraph-demo-fed2) +- If you learn best by doing, this [interactive course](https://www.apollographql.com/tutorials/voyage-part1) teaches you to build an example supergraph using Apollo Federation. ### Further documentation -Apollo's docs offer these sections: +Once you're ready to apply federation to your own APIs, these docs sections can help you get started: -- A [Quickstart tutorial](./quickstart/setup/) that walks you through setting up an Apollo Federation supergraph -- Details on [subgraphs](./building-supergraphs/subgraphs-overview) and [routers](./building-supergraphs/router) in **Building Your Supergraph** -- A conceptual overview of writing [**Federated Schemas**](./federated-types/overview) -- A [guide on using Apollo GraphOS](./managed-federation) to automate and manage deployments of your federated schemas (this is also known as **Managed Federation**) +- Conceptual overview of [Federated Schemas](./federated-types/overview) +- [Guide on using Apollo GraphOS](./managed-federation) to automate and manage deployments of your federated schemas (this is also known as **Managed Federation**) - Reference materials for: - [Performance considerations](./performance/caching) - [Debugging and metrics](./errors) @@ -160,7 +161,7 @@ Apollo's docs offer these sections: ### Best practices -The [Supergraph Architecture Framework](https://saf.apollographql.com/) (SAF) is a set of best practices for building a reliable, secure, performant, and developer-friendly graph. You can use the SAF assessment to quantify your graph's current state and identify areas for improvement. +Whether your supergraph implementation is already underway or just starting, you can use the [Supergraph Architecture Framework](https://saf.apollographql.com/) (SAF) to learn about best practices. The SAF includes an assessment you can take to quantify your supergraph's current state and identify areas for improvement. From 80e549c14b3b9df0c427a1998ea7e15bfe54ba35 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Tue, 14 Nov 2023 15:10:33 -0800 Subject: [PATCH 23/42] address review comments --- docs/source/managed-federation/deployment.mdx | 2 +- docs/source/managed-federation/overview.mdx | 5 +++-- docs/source/managed-federation/setup.mdx | 2 +- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index 2db78a79a..1eae66e59 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -126,7 +126,7 @@ Specifically, for deployments that run in different production environments, suc ### Example blue-green deployment -A blue-green deployment strategy uses two environments: one environment (blue) serves the schema variant for live traffic, while the other environment (green) uses a variant for a new release that's under development. When the new release is ready, traffic is migrated from the blue to the green environment. This cycle repeats with each new release. +A blue-green deployment strategy uses two environments: one environment (blue) serves the schema variant for live traffic, and the other environment (green) uses a variant for a new release that's under development. When the new release is ready, traffic is migrated from the blue to the green environment. This cycle repeats with each new release. As an example, follow these steps to deploy with a supergraph schema of a new release (green) environment: diff --git a/docs/source/managed-federation/overview.mdx b/docs/source/managed-federation/overview.mdx index fafea7d65..66d1637a1 100644 --- a/docs/source/managed-federation/overview.mdx +++ b/docs/source/managed-federation/overview.mdx @@ -1,11 +1,12 @@ --- title: Managed federation overview -description: Let Apollo GraphOS manage validating and composing your subgraph schemas into a federated, supergraph schema and configuration for your routers. +description: Let Apollo GraphOS manage CI/CD of your supergraph including schema validation, composition, and configuration. +subtitle: Manage supergraph CI/CD with Apollo GraphOS --- [Apollo GraphOS](/graphos/) provides **managed federation** support for graphs that use Apollo Federation. -With managed federation, you maintain subgraphs and delegate GraphOS to manage the validation, composition, and update of your supergraph: +With managed federation, you maintain subgraphs and delegate GraphOS to manage CI/CD tasks including the validation, composition, and update of your supergraph: * Your subgraphs publish their schemas to GraphOS, which stores them in its schema registry. GraphOS then [validates](./federated-schema-checks) and [composes](../federated-types/composition/) them into a supergraph schema. diff --git a/docs/source/managed-federation/setup.mdx b/docs/source/managed-federation/setup.mdx index 09a4ac9e3..c667e13b2 100644 --- a/docs/source/managed-federation/setup.mdx +++ b/docs/source/managed-federation/setup.mdx @@ -89,7 +89,7 @@ If you've already set up Apollo Federation _without_ connecting your router to G The `--supergraph` option applies in scenarios where the router doesn't retrieve the supergraph schema by polling Apollo Uplink. These include: -* For enabling different production environments (such as blue-green deployments) to refer to a single graph variant, the supergraph schema for each production environment can be composed and retrieved by a workflow using Platform APIs, so that the routers of each environment use the supergraph schema corresponding to the environment. +* **Enabling different deployment environments to refer to a single graph variant**, for example, for [blue-green deployment](https://en.wikipedia.org/wiki/Blue%E2%80%93green_deployment): Use a workflow with the [Platform API](/graphos/platform-api/) to compose and retrieve the supergraph schema for each environment. This enables each environment's router to use the environment's supergraph schema, and then a single graph variant can capture and analyze the operations and traffic of either environment when deployed. * **Unmanaged federation**: The Rover CLI composes the supergraph schema and passes the schema's file path to the router via the `--supergraph` option. From a0bdd7cb056ccdc6d9f6ec6bd6a16380d18f65b9 Mon Sep 17 00:00:00 2001 From: Chris Lenfest Date: Wed, 15 Nov 2023 09:19:13 -0600 Subject: [PATCH 24/42] Fix removeInputsFromSelection to only remove inputs (#2859) removeInputsFromSelection is tasked with removing inputs to a FetchGroup from the fetch group so that we don't retrieve the same values twice (and FetchGroups that don't functionally do anything can be removed). There was a bug in the code that meant that in certain cases, things that were required were actually being removed. This could manifest in subgraph jumps not being possible because the key it was using to make the jump was not available. Fixes #2805 --- .changeset/pink-ducks-fail.md | 6 + .../src/__tests__/buildPlan.test.ts | 154 +++++++++++++++++- query-planner-js/src/buildPlan.ts | 12 +- 3 files changed, 165 insertions(+), 7 deletions(-) create mode 100644 .changeset/pink-ducks-fail.md diff --git a/.changeset/pink-ducks-fail.md b/.changeset/pink-ducks-fail.md new file mode 100644 index 000000000..46f4939c9 --- /dev/null +++ b/.changeset/pink-ducks-fail.md @@ -0,0 +1,6 @@ +--- +"@apollo/query-planner": patch +--- + +Fix query planning bug where keys or required fields can sometimes reach subgraphs with null values. ([#2805](https://github.com/apollographql/federation/issues/2805)) + \ No newline at end of file diff --git a/query-planner-js/src/__tests__/buildPlan.test.ts b/query-planner-js/src/__tests__/buildPlan.test.ts index d3cba514b..f0717e03d 100644 --- a/query-planner-js/src/__tests__/buildPlan.test.ts +++ b/query-planner-js/src/__tests__/buildPlan.test.ts @@ -3810,7 +3810,7 @@ describe('Fed1 supergraph handling', () => { }); describe('Named fragments preservation', () => { - it('works with nested fragments', () => { + it('works with nested fragments 1', () => { const subgraph1 = { name: 'Subgraph1', typeDefs: gql` @@ -7821,3 +7821,155 @@ test('avoid considering indirect paths from the root when a more direct one exis 4, ); }); + +describe('@requires references external field indirectly', () => { + it('key where @external is not at top level of selection of requires', () => { + // Field issue where we were seeing a FetchGroup created where the fields used by the key to jump subgraphs + // were not properly fetched. In the below test, this test will ensure that 'k2' is properly collected + // before it is used + const subgraph1 = { + name: 'A', + typeDefs: gql` + type Query { + u: U! + } + + type U @key(fields: "k1 { id }") { + k1: K + } + + type K @key(fields: "id") { + id: ID! + } + `, + }; + const subgraph2 = { + name: 'B', + typeDefs: gql` + type U @key(fields: "k1 { id }") @key(fields: "k2") { + k1: K! + k2: ID! + v: V! @external + f: ID! @requires(fields: "v { v }") + f2: Int! + } + + type K @key(fields: "id") { + id: ID! + } + + type V @key(fields: "id") { + id: ID! + v: String! @external + } + `, + }; + const subgraph3 = { + name: 'C', + typeDefs: gql` + type U @key(fields: "k1 { id }") @key(fields: "k2") { + k1: K! + k2: ID! + v: V! + } + + type K @key(fields: "id") { + id: ID! + } + + type V @key(fields: "id") { + id: ID! + v: String! + } + `, + }; + + const [api, queryPlanner] = composeAndCreatePlanner( + subgraph1, + subgraph2, + subgraph3, + ); + const operation = operationFromDocument( + api, + gql` + { + u { + f + } + } + `, + ); + + const plan = queryPlanner.buildQueryPlan(operation); + expect(plan).toMatchInlineSnapshot(` + QueryPlan { + Sequence { + Fetch(service: "A") { + { + u { + __typename + k1 { + id + } + } + } + }, + Flatten(path: "u") { + Fetch(service: "B") { + { + ... on U { + __typename + k1 { + id + } + } + } => + { + ... on U { + k2 + } + } + }, + }, + Flatten(path: "u") { + Fetch(service: "C") { + { + ... on U { + __typename + k2 + } + } => + { + ... on U { + v { + v + } + } + } + }, + }, + Flatten(path: "u") { + Fetch(service: "B") { + { + ... on U { + __typename + v { + v + } + k1 { + id + } + } + } => + { + ... on U { + f + } + } + }, + }, + }, + } + `); + }); +}); diff --git a/query-planner-js/src/buildPlan.ts b/query-planner-js/src/buildPlan.ts index d677c03a6..e31a81754 100644 --- a/query-planner-js/src/buildPlan.ts +++ b/query-planner-js/src/buildPlan.ts @@ -944,7 +944,7 @@ class FetchGroup { // `inputs.contains(selection)`, so if a group is shown useful, it means that there // is some selections not in the inputs, but as long as we add to selections (and we // never remove from selections; `MutableSelectionSet` don't have removing methods), - // then this won't change. Only changing inputs may require some recomputation. + // then this won't change. Only changing inputs may require some recomputation. this.isKnownUseful = false; } } @@ -1188,7 +1188,7 @@ class FetchGroup { if (inputs) { this.cachedCost = undefined; const updated = inputs.selectionSets().reduce((prev, value) => prev.minus(value), this.selection); - this._selection = MutableSelectionSet.ofWithMemoized(this.selection.minus(updated), conditionsMemoizer); + this._selection = MutableSelectionSet.ofWithMemoized(updated, conditionsMemoizer); } } @@ -1706,7 +1706,7 @@ function withFieldAliased(selectionSet: SelectionSet, aliases: FieldToAlias[]): const field = selection.element; const alias = pathElement && atCurrentLevel.get(pathElement); return !alias && selection.selectionSet === updatedSelectionSet - ? selection + ? selection : selection.withUpdatedComponents(alias ? field.withUpdatedAlias(alias.alias) : field, updatedSelectionSet); } else { return selection.selectionSet === updatedSelectionSet @@ -3701,8 +3701,8 @@ function addTypenameFieldForAbstractTypesInNamedFragments(fragments: NamedFragme } /** - * Given a selection select (`selectionSet`) and given a set of directive applications that can be eliminated (`unneededDirectives`; in - * practice those are conditionals (@skip and @include) already accounted for), returns an equivalent selection set but with unecessary + * Given a selection select (`selectionSet`) and given a set of directive applications that can be eliminated (`unneededDirectives`; in + * practice those are conditionals (@skip and @include) already accounted for), returns an equivalent selection set but with unecessary * "starting" fragments having the unneeded condition/directives removed. */ function removeUnneededTopLevelFragmentDirectives( @@ -3969,7 +3969,7 @@ function computeGroupsForTree( const inputSelections = newCompositeTypeSelectionSet(inputType); inputSelections.updates().add(edge.conditions!); newGroup.addInputs( - wrapInputsSelections(inputType, inputSelections.get(), newContext), + wrapInputsSelections(inputType, inputSelections.get(), newContext), computeInputRewritesOnKeyFetch(inputType.name, destType), ); From 97a2175d54eba837aeca51dd2905df86a62cce7e Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Wed, 15 Nov 2023 13:41:42 -0800 Subject: [PATCH 25/42] address review comments --- docs/shared/diagrams/managed-federation.mdx | 17 +++++++++++++++++ docs/source/index.mdx | 20 +++----------------- docs/source/managed-federation/overview.mdx | 20 +++----------------- docs/source/managed-federation/setup.mdx | 2 +- 4 files changed, 24 insertions(+), 35 deletions(-) create mode 100644 docs/shared/diagrams/managed-federation.mdx diff --git a/docs/shared/diagrams/managed-federation.mdx b/docs/shared/diagrams/managed-federation.mdx new file mode 100644 index 000000000..d753fb425 --- /dev/null +++ b/docs/shared/diagrams/managed-federation.mdx @@ -0,0 +1,17 @@ +```mermaid +graph LR; + subgraph "Your infrastructure" + serviceA[Products subgraph]; + serviceB[Reviews subgraph]; + router([Router]); + end + subgraph "Apollo GraphOS" + registry{{Schema Registry}}; + uplink{{Uplink}} + end + serviceA & serviceB -->|"Publishes
schema"| registry; + registry -->|"Updates
config"| uplink; + router -->|Polls for config changes| uplink; + class registry secondary; + class uplink secondary; +``` diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 8ca0c7fd7..a36463d53 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -3,6 +3,8 @@ title: Introduction to Apollo Federation description: Combine GraphQL APIs into a unified supergraph --- +import ManagedFederationDiagram from '../../shared/diagrams/managed-federation.mdx'; + **Apollo Federation** is a powerful, open architecture for creating a **supergraph** that combines multiple GraphQL APIs: ```mermaid @@ -345,23 +347,7 @@ These resulting schemas provide the best of both worlds: Your router can operate in **managed federation** mode, where [Apollo GraphOS](/graphos/) acts as the source of truth for your supergraph's configuration: -```mermaid -graph LR; - subgraph "Your infrastructure" - serviceA[Products
subgraph]; - serviceB[Reviews
subgraph]; - gateway([Router]); - end - subgraph "Apollo GraphOS" - registry{{Apollo Schema
Registry}}; - uplink{{Apollo
Uplink}} - end - serviceA & serviceB -->|Publishes
schema| registry; - registry -->|Updates
supergraph config| uplink; - gateway -->|Polls for supergraph changes| uplink; - class registry secondary; - class uplink secondary; -``` + This mode helps multiple teams working on a supergraph to coordinate when and how to change individual subgraphs. It's recommended for all supergraphs. For more information, read [Managed federation overview](./managed-federation/overview/). diff --git a/docs/source/managed-federation/overview.mdx b/docs/source/managed-federation/overview.mdx index 66d1637a1..2faf5d5ae 100644 --- a/docs/source/managed-federation/overview.mdx +++ b/docs/source/managed-federation/overview.mdx @@ -4,6 +4,8 @@ description: Let Apollo GraphOS manage CI/CD of your supergraph including schema subtitle: Manage supergraph CI/CD with Apollo GraphOS --- +import ManagedFederationDiagram from '../../shared/diagrams/managed-federation.mdx'; + [Apollo GraphOS](/graphos/) provides **managed federation** support for graphs that use Apollo Federation. With managed federation, you maintain subgraphs and delegate GraphOS to manage CI/CD tasks including the validation, composition, and update of your supergraph: @@ -12,23 +14,7 @@ With managed federation, you maintain subgraphs and delegate GraphOS to manage C * Your routers can poll GraphOS—specifically, its [Apollo Uplink](./uplink) endpoint—to get the latest validated supergraph schema and other configurations. -```mermaid -graph LR; - subgraph "Your infrastructure" - serviceA[Products
subgraph]; - serviceB[Reviews
subgraph]; - router([Router]); - end - subgraph "Apollo GraphOS" - registry{{Apollo Schema
Registry}}; - uplink{{Apollo
Uplink}} - end - serviceA & serviceB -->|Publishes
schema| registry; - registry -->|Updates
config| uplink; - router -->|Polls for config changes| uplink; - class registry secondary; - class uplink secondary; -``` + ## Benefits of managed federation diff --git a/docs/source/managed-federation/setup.mdx b/docs/source/managed-federation/setup.mdx index c667e13b2..6f42db448 100644 --- a/docs/source/managed-federation/setup.mdx +++ b/docs/source/managed-federation/setup.mdx @@ -99,7 +99,7 @@ For other scenarios where the router retrieves the supergraph schema from Apollo ./router --config ./router.yaml ``` -With managed federation, composition can be performed by _GraphOS_, and the router regularly polls for an updated schema from Apollo Uplink. This enables you to add, remove, and modify your subgraphs _without_ needing to restart your router. +With federation managed by GraphOS, composition is performed when subgraph schemas are published, and the router regularly polls for an updated supergraph schema from Apollo Uplink. This enables you to add, remove, and modify your subgraphs _without_ needing to restart your router. ## 4. Connect your router to GraphOS From a2a2cf9742b35e2d8f30b6a059e4159759c7c328 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Wed, 15 Nov 2023 13:50:03 -0800 Subject: [PATCH 26/42] add preview callouts --- docs/source/managed-federation/deployment.mdx | 2 ++ docs/source/managed-federation/uplink.mdx | 2 ++ 2 files changed, 4 insertions(+) diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index 1eae66e59..481e0695b 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -126,6 +126,8 @@ Specifically, for deployments that run in different production environments, suc ### Example blue-green deployment + + A blue-green deployment strategy uses two environments: one environment (blue) serves the schema variant for live traffic, and the other environment (green) uses a variant for a new release that's under development. When the new release is ready, traffic is migrated from the blue to the green environment. This cycle repeats with each new release. As an example, follow these steps to deploy with a supergraph schema of a new release (green) environment: diff --git a/docs/source/managed-federation/uplink.mdx b/docs/source/managed-federation/uplink.mdx index 8cc046535..7dc5ef6d4 100644 --- a/docs/source/managed-federation/uplink.mdx +++ b/docs/source/managed-federation/uplink.mdx @@ -144,6 +144,8 @@ If your supergraph schema _does_ exceed 6MB, you can set up a [build status webh ## Bypassing Uplink + + In advanced use cases, you may want your router to use a supergraph schema different than the latest validated schema provided by Uplink. For example, you have different deployment environments for the same [graph variant](/graphos/graphs/#variants), and you want everything that managed federation provides except for your routers to use supergraph schemas specific to their deployment environment. For this scenario, you can follow a workflow that, instead of retrieving supergraph schemas from Uplink, uses the [GraphOS Platform API](/graphos/platform-api) to retrieve a supergraph schema for a specific [GraphOS launch](/graphos/delivery/launches). The workflow, in summary: From 907e80381123a0e5602d76ae03bd37b8ce681775 Mon Sep 17 00:00:00 2001 From: Edward Huang <18322228+shorgi@users.noreply.github.com> Date: Wed, 15 Nov 2023 14:03:10 -0800 Subject: [PATCH 27/42] Update docs/source/managed-federation/setup.mdx Co-authored-by: Maria Elisabeth Schreiber --- docs/source/managed-federation/setup.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/managed-federation/setup.mdx b/docs/source/managed-federation/setup.mdx index 6f42db448..dde1ad501 100644 --- a/docs/source/managed-federation/setup.mdx +++ b/docs/source/managed-federation/setup.mdx @@ -89,7 +89,7 @@ If you've already set up Apollo Federation _without_ connecting your router to G The `--supergraph` option applies in scenarios where the router doesn't retrieve the supergraph schema by polling Apollo Uplink. These include: -* **Enabling different deployment environments to refer to a single graph variant**, for example, for [blue-green deployment](https://en.wikipedia.org/wiki/Blue%E2%80%93green_deployment): Use a workflow with the [Platform API](/graphos/platform-api/) to compose and retrieve the supergraph schema for each environment. This enables each environment's router to use the environment's supergraph schema, and then a single graph variant can capture and analyze the operations and traffic of either environment when deployed. +* **Enabling different deployment environments to refer to a single graph variant**, for example, for [blue-green deployment](./deployment/#example-blue-green-deployment): Use a workflow with the [Platform API](/graphos/platform-api/) to compose and retrieve the supergraph schema for each environment. This enables each environment's router to use the environment's supergraph schema, and then a single graph variant can capture and analyze the operations and traffic of either environment when deployed. * **Unmanaged federation**: The Rover CLI composes the supergraph schema and passes the schema's file path to the router via the `--supergraph` option. From e496e114d9f13f4b62dcdb3b6d26fecabbaa780f Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Wed, 15 Nov 2023 14:49:05 -0800 Subject: [PATCH 28/42] address review comments --- docs/source/managed-federation/deployment.mdx | 2 ++ docs/source/managed-federation/uplink.mdx | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index 481e0695b..366d4b067 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -205,6 +205,8 @@ As an example, follow these steps to deploy with a supergraph schema of a new re 1. Deploy your routers with the [`-s` or `--supergraph` option](/router/configuration/overview/#-s----supergraph) to specify the supergraph schema. + * Specifying the `-s` or `--supergraph` option disables polling for the schema from Uplink. + * For an example using the option in a `docker run` command, see [Specifying the supergraph](/router/containerization/docker/#specifying-the-supergraph). ### Example canary deployment diff --git a/docs/source/managed-federation/uplink.mdx b/docs/source/managed-federation/uplink.mdx index 7dc5ef6d4..6a14b7b47 100644 --- a/docs/source/managed-federation/uplink.mdx +++ b/docs/source/managed-federation/uplink.mdx @@ -150,7 +150,7 @@ In advanced use cases, you may want your router to use a supergraph schema diffe For this scenario, you can follow a workflow that, instead of retrieving supergraph schemas from Uplink, uses the [GraphOS Platform API](/graphos/platform-api) to retrieve a supergraph schema for a specific [GraphOS launch](/graphos/delivery/launches). The workflow, in summary: -1. When deploying your graphs, publish your subgraphs in a batch using a GraphOS Platform API. +1. When deploying your graphs, publish your subgraphs in a batch using the GraphOS Platform API. * The Platform API triggers a launch (and possible downstream launches for contracts) and returns the launch ID (and downstream launch IDs, if necessary). 1. Poll for the launch status, until the launch (and all downstream launches) has completed successfully. 1. Retrieve the supergraph schema of the successful launch by calling the Platform API with the launch ID. From 5febe6f72bd9108228d03161d9e1b371d4aa553e Mon Sep 17 00:00:00 2001 From: Edward Huang <18322228+shorgi@users.noreply.github.com> Date: Wed, 15 Nov 2023 16:57:43 -0800 Subject: [PATCH 29/42] Apply suggestions from code review Co-authored-by: timbotnik --- docs/source/managed-federation/deployment.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index 366d4b067..b12e6a854 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -118,11 +118,11 @@ The next time it starts up or polls, your router obtains an updated configuratio ## Using variants to control rollout -Your deployment model may require deploying a specific version of your graph, for example, for blue-green or canary deployments. With managed federation, you can control which version of your graph your router fleet uses. In most cases, rolling over all of your router instances to a new schema version is safe, assuming you've used [schema checks](./federated-schema-checks/) to confirm that your changes are backward compatible. +Your deployment model may require deploying a specific version of your graph, for example, for blue-green or canary deployments. With managed federation, you can control which version of your schema your router fleet uses. In most cases, rolling over all of your router instances to a new schema version is safe, assuming you've used [schema checks](./federated-schema-checks/) to confirm that your changes are backward compatible. However, changes at the router level might involve a variety of different updates, such as [migrating entities](../entities-advanced/#migrating-entities-and-fields) from one subgraph to another. If your infrastructure requires a more advanced deployment process, you can use [graph variants](/graphos/graphs/#variants) to manage router fleets running with different configurations. -Specifically, for deployments that run in different production environments, such as blue-green deployments, you can configure your environments to refer to a single graph variant by pinning each environment's supergraph schema to your routers at deployment time. Using a single variant between different production environments enables Studio to get usage reports and analyze the combined production traffic of all environments. +Specifically, for deployments that require progressive rollout, such as blue-green deployments, you can configure your environments to refer to a single graph variant by pinning each environment's supergraph schema to your routers at deployment time. Using a single variant between different production environments enables Studio to get usage reports and analyze the combined production traffic of all environments, as well as providing a consistent changelog of your schema over time. ### Example blue-green deployment @@ -154,6 +154,8 @@ As an example, follow these steps to deploy with a supergraph schema of a new re id downstreamLaunches { id + graphVariant + status } } } From 6ba34877e291b10c2c9befbdbfe3241d45863b68 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Wed, 15 Nov 2023 21:08:17 -0800 Subject: [PATCH 30/42] address review comments --- docs/source/managed-federation/deployment.mdx | 36 +++++++++++++++---- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index b12e6a854..915f22568 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -116,13 +116,17 @@ rover subgraph delete my-supergraph@my-variant --name accounts The next time it starts up or polls, your router obtains an updated configuration that reflects the removed subgraph. -## Using variants to control rollout +## Advanced deployment workflows -Your deployment model may require deploying a specific version of your graph, for example, for blue-green or canary deployments. With managed federation, you can control which version of your schema your router fleet uses. In most cases, rolling over all of your router instances to a new schema version is safe, assuming you've used [schema checks](./federated-schema-checks/) to confirm that your changes are backward compatible. +With managed federation, you can control which version of your schema your router fleet uses. In most cases, rolling over all of your router instances to a new schema version is safe, assuming you've used [schema checks](./federated-schema-checks/) to confirm that your changes are backward compatible. Your deployment model, however, may require an advanced workflow to deploy a specific version of a schema. -However, changes at the router level might involve a variety of different updates, such as [migrating entities](../entities-advanced/#migrating-entities-and-fields) from one subgraph to another. If your infrastructure requires a more advanced deployment process, you can use [graph variants](/graphos/graphs/#variants) to manage router fleets running with different configurations. +Two types of advanced deployment workflows: -Specifically, for deployments that require progressive rollout, such as blue-green deployments, you can configure your environments to refer to a single graph variant by pinning each environment's supergraph schema to your routers at deployment time. Using a single variant between different production environments enables Studio to get usage reports and analyze the combined production traffic of all environments, as well as providing a consistent changelog of your schema over time. +* **Blue-green deployment workflow**. For deployments that require progressive rollout, such as blue-green deployments, you can configure your environments to refer to a single [graph variant](/graphos/graphs/#variants) by pinning each environment's supergraph schema to your routers at deployment time. Using a single variant between different production environments enables GraphOS Studio to get usage reports and analyze the combined production traffic of all environments, as well as providing a consistent changelog of your schema over time. + +* **Graph variant workflow**. Changes at the router level might involve a variety of different updates, such as [migrating entities](../entities-advanced/#migrating-entities-and-fields) from one subgraph to another. If your infrastructure requires a more advanced deployment process to handle the different router updates, you can use [graph variants](/graphos/graphs/#variants) to manage router fleets running with different configurations. + + A common use for graph variants is [contracts](/graphos/delivery/contracts/), for example, to create separate contract variants for the public and private APIs of a supergraph schema. ### Example blue-green deployment @@ -130,7 +134,7 @@ Specifically, for deployments that require progressive rollout, such as blue-gre A blue-green deployment strategy uses two environments: one environment (blue) serves the schema variant for live traffic, and the other environment (green) uses a variant for a new release that's under development. When the new release is ready, traffic is migrated from the blue to the green environment. This cycle repeats with each new release. -As an example, follow these steps to deploy with a supergraph schema of a new release (green) environment: +As an example, follow these steps to deploy with a supergraph schema of a new release (green) environment; the example uses the [GraphOS Platform API](/graphos/platform-api/) to perform custom GraphOS actions: 1. Publish all the release's subgraphs at once using the Platform API [`publishSubgraphs` mutation](https://studio.apollographql.com/graph/apollo-platform/variant/main/schema/reference/objects/GraphMutation#publishSubgraphs). @@ -165,6 +169,12 @@ As an example, follow these steps to deploy with a supergraph schema of a new re This initiates a [launch](/graphos/delivery/launches/), as well as any downstream launches necessary for [contracts](graphos/delivery/contracts/#automatic-updates). It returns the launch IDs, with downstream launch IDs configured to return synchronously (`downstreamLaunchInitiation: "SYNC"`) with the mutation. + + + For contracts, the contract variants are gotten from this query with ` Launch.graphVariant / downstreamLaunches { graphVariant }`. These are used in queries in following steps. + + + 1. Poll for the completed launch and any downstream launches. ```graphql @@ -181,6 +191,12 @@ As an example, follow these steps to deploy with a supergraph schema of a new re ``` + + + When polling for a contract, the `$graphVariant` argument of this query must refer to a contract variant. You can get it from the query in step 1, from `Launch.graphVariant / downstreamLaunches { graphVariant }`. + + + 1. After the launch and downstream launches have completed, retrieve the supergraph schema of the launch. ```graphql @@ -205,6 +221,12 @@ As an example, follow these steps to deploy with a supergraph schema of a new re ``` + + + When retrieving for a contract, the `$graphVariant` argument of this query must refer to a contract variant. You can get it from the query in step 1, from `Launch.graphVariant / downstreamLaunches { graphVariant }`. + + + 1. Deploy your routers with the [`-s` or `--supergraph` option](/router/configuration/overview/#-s----supergraph) to specify the supergraph schema. * Specifying the `-s` or `--supergraph` option disables polling for the schema from Uplink. @@ -215,7 +237,7 @@ As an example, follow these steps to deploy with a supergraph schema of a new re A canary deployment applies graph updates to a small subset of your deployment environment before rolling it out for your entire environment. -To configure a canary deployment, you might maintain two production graph variants in Apollo Studio, one named `prod` and the other named `prod-canary`. To deploy a change to a subgraph named `launches`, you might perform the following steps: +To configure a canary deployment, you might maintain two production graph variants in GraphOS Studio, one named `prod` and the other named `prod-canary`. To deploy a change to a subgraph named `launches`, you might perform the following steps: 1. Check the changes in `launches` against both `prod` and `prod-canary`: ```shell @@ -235,7 +257,7 @@ To configure a canary deployment, you might maintain two production graph varian rover subgraph publish my-supergraph@prod --name=launches --schema ./launches/schema.graphql ``` -If your canary variant [reports metrics to GraphOS](/graphos/metrics/), you can use [Apollo Studio](https://studio.apollographql.com?referrer=docs-content) to verify a canary's performance before rolling out changes to the rest of the graph. You can also use variants to support a variety of other advanced deployment workflows, such as blue/green deployments. +If your canary variant [reports metrics to GraphOS](/graphos/metrics/), you can use [GraphOS Studio](https://studio.apollographql.com?referrer=docs-content) to verify a canary's performance before rolling out changes to the rest of the graph. You can also use variants to support a variety of other advanced deployment workflows, such as blue/green deployments. ## Modifying query-planning logic From b1980e249c0eb93442c22f1179207b624def0fd1 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Wed, 15 Nov 2023 22:08:44 -0800 Subject: [PATCH 31/42] Address review comments --- docs/source/managed-federation/deployment.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index 915f22568..001671b0e 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -171,7 +171,7 @@ As an example, follow these steps to deploy with a supergraph schema of a new re - For contracts, the contract variants are gotten from this query with ` Launch.graphVariant / downstreamLaunches { graphVariant }`. These are used in queries in following steps. + For contracts, you can also request that any downstream launches return the variant associated with each launch, for example, `downstreamLaunches { graphVariant }`. When querying for a specific launch, be sure to pass the variant associated with the launch in the following steps. @@ -193,7 +193,7 @@ As an example, follow these steps to deploy with a supergraph schema of a new re - When polling for a contract, the `$graphVariant` argument of this query must refer to a contract variant. You can get it from the query in step 1, from `Launch.graphVariant / downstreamLaunches { graphVariant }`. + When polling for a contract, the `$graphVariant` argument of this query must refer to the contract variant rather than the base variant. You can get it from the query in step 1, from `Launch.graphVariant / downstreamLaunches { graphVariant }`. From 824c65a16fcaafdd55c1c06c6c7a35fd681f46fa Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Thu, 16 Nov 2023 09:19:14 -0800 Subject: [PATCH 32/42] trigger checks From a6878394ddb161a085d7206e4f4f0f0111e84ba9 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 16 Nov 2023 16:39:40 -0600 Subject: [PATCH 33/42] Version Packages (#2861) Co-authored-by: github-actions[bot] --- .changeset/pink-ducks-fail.md | 6 ---- composition-js/CHANGELOG.md | 7 ++++ composition-js/package.json | 6 ++-- .../CHANGELOG.md | 2 ++ .../package.json | 2 +- gateway-js/CHANGELOG.md | 8 +++++ gateway-js/package.json | 8 ++--- internals-js/CHANGELOG.md | 2 ++ internals-js/package.json | 2 +- package-lock.json | 32 +++++++++---------- query-graphs-js/CHANGELOG.md | 6 ++++ query-graphs-js/package.json | 4 +-- query-planner-js/CHANGELOG.md | 10 ++++++ query-planner-js/package.json | 6 ++-- subgraph-js/CHANGELOG.md | 6 ++++ subgraph-js/package.json | 4 +-- 16 files changed, 73 insertions(+), 38 deletions(-) delete mode 100644 .changeset/pink-ducks-fail.md diff --git a/.changeset/pink-ducks-fail.md b/.changeset/pink-ducks-fail.md deleted file mode 100644 index 46f4939c9..000000000 --- a/.changeset/pink-ducks-fail.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -"@apollo/query-planner": patch ---- - -Fix query planning bug where keys or required fields can sometimes reach subgraphs with null values. ([#2805](https://github.com/apollographql/federation/issues/2805)) - \ No newline at end of file diff --git a/composition-js/CHANGELOG.md b/composition-js/CHANGELOG.md index 1e108479f..9e2beb426 100644 --- a/composition-js/CHANGELOG.md +++ b/composition-js/CHANGELOG.md @@ -1,5 +1,12 @@ # CHANGELOG for `@apollo/composition` +## 2.5.7 +### Patch Changes + +- Updated dependencies []: + - @apollo/federation-internals@2.5.7 + - @apollo/query-graphs@2.5.7 + ## 2.5.6 ### Patch Changes diff --git a/composition-js/package.json b/composition-js/package.json index 7d01c44a0..eada3a1aa 100644 --- a/composition-js/package.json +++ b/composition-js/package.json @@ -1,6 +1,6 @@ { "name": "@apollo/composition", - "version": "2.5.6", + "version": "2.5.7", "description": "Apollo Federation composition utilities", "main": "dist/index.js", "types": "dist/index.d.ts", @@ -27,8 +27,8 @@ "access": "public" }, "dependencies": { - "@apollo/federation-internals": "2.5.6", - "@apollo/query-graphs": "2.5.6" + "@apollo/federation-internals": "2.5.7", + "@apollo/query-graphs": "2.5.7" }, "peerDependencies": { "graphql": "^16.5.0" diff --git a/federation-integration-testsuite-js/CHANGELOG.md b/federation-integration-testsuite-js/CHANGELOG.md index c79e7b4ec..6decd3ec2 100644 --- a/federation-integration-testsuite-js/CHANGELOG.md +++ b/federation-integration-testsuite-js/CHANGELOG.md @@ -1,5 +1,7 @@ # CHANGELOG for `federation-integration-testsuite-js` +## 2.5.7 + ## 2.5.6 ## 2.5.5 diff --git a/federation-integration-testsuite-js/package.json b/federation-integration-testsuite-js/package.json index bfff2165c..708bd3c0d 100644 --- a/federation-integration-testsuite-js/package.json +++ b/federation-integration-testsuite-js/package.json @@ -1,7 +1,7 @@ { "name": "apollo-federation-integration-testsuite", "private": true, - "version": "2.5.6", + "version": "2.5.7", "description": "Apollo Federation Integrations / Test Fixtures", "main": "dist/index.js", "types": "dist/index.d.ts", diff --git a/gateway-js/CHANGELOG.md b/gateway-js/CHANGELOG.md index 2336bfa0f..60213272c 100644 --- a/gateway-js/CHANGELOG.md +++ b/gateway-js/CHANGELOG.md @@ -1,5 +1,13 @@ # CHANGELOG for `@apollo/gateway` +## 2.5.7 +### Patch Changes + +- Updated dependencies [[`a0bdd7cb`](https://github.com/apollographql/federation/commit/a0bdd7cb056ccdc6d9f6ec6bd6a16380d18f65b9)]: + - @apollo/query-planner@2.5.7 + - @apollo/composition@2.5.7 + - @apollo/federation-internals@2.5.7 + ## 2.5.6 ### Patch Changes diff --git a/gateway-js/package.json b/gateway-js/package.json index dc303cd71..232a7138b 100644 --- a/gateway-js/package.json +++ b/gateway-js/package.json @@ -1,6 +1,6 @@ { "name": "@apollo/gateway", - "version": "2.5.6", + "version": "2.5.7", "description": "Apollo Gateway", "author": "Apollo ", "main": "dist/index.js", @@ -25,9 +25,9 @@ "access": "public" }, "dependencies": { - "@apollo/composition": "2.5.6", - "@apollo/federation-internals": "2.5.6", - "@apollo/query-planner": "2.5.6", + "@apollo/composition": "2.5.7", + "@apollo/federation-internals": "2.5.7", + "@apollo/query-planner": "2.5.7", "@apollo/server-gateway-interface": "^1.1.0", "@apollo/usage-reporting-protobuf": "^4.1.0", "@apollo/utils.createhash": "^2.0.0", diff --git a/internals-js/CHANGELOG.md b/internals-js/CHANGELOG.md index 362eb4e95..2ce664d8a 100644 --- a/internals-js/CHANGELOG.md +++ b/internals-js/CHANGELOG.md @@ -1,5 +1,7 @@ # CHANGELOG for `@apollo/federation-internals` +## 2.5.7 + ## 2.5.6 ### Patch Changes diff --git a/internals-js/package.json b/internals-js/package.json index 6d3c28690..d38547a8f 100644 --- a/internals-js/package.json +++ b/internals-js/package.json @@ -1,6 +1,6 @@ { "name": "@apollo/federation-internals", - "version": "2.5.6", + "version": "2.5.7", "description": "Apollo Federation internal utilities", "main": "dist/index.js", "types": "dist/index.d.ts", diff --git a/package-lock.json b/package-lock.json index 282477050..eca75c9fc 100644 --- a/package-lock.json +++ b/package-lock.json @@ -71,11 +71,11 @@ }, "composition-js": { "name": "@apollo/composition", - "version": "2.5.6", + "version": "2.5.7", "license": "SEE LICENSE IN ./LICENSE", "dependencies": { - "@apollo/federation-internals": "2.5.6", - "@apollo/query-graphs": "2.5.6" + "@apollo/federation-internals": "2.5.7", + "@apollo/query-graphs": "2.5.7" }, "engines": { "node": ">=14.15.0" @@ -86,7 +86,7 @@ }, "federation-integration-testsuite-js": { "name": "apollo-federation-integration-testsuite", - "version": "2.5.6", + "version": "2.5.7", "license": "SEE LICENSE IN ./LICENSE", "dependencies": { "graphql-tag": "^2.12.6", @@ -95,12 +95,12 @@ }, "gateway-js": { "name": "@apollo/gateway", - "version": "2.5.6", + "version": "2.5.7", "license": "SEE LICENSE IN ./LICENSE", "dependencies": { - "@apollo/composition": "2.5.6", - "@apollo/federation-internals": "2.5.6", - "@apollo/query-planner": "2.5.6", + "@apollo/composition": "2.5.7", + "@apollo/federation-internals": "2.5.7", + "@apollo/query-planner": "2.5.7", "@apollo/server-gateway-interface": "^1.1.0", "@apollo/usage-reporting-protobuf": "^4.1.0", "@apollo/utils.createhash": "^2.0.0", @@ -126,7 +126,7 @@ }, "internals-js": { "name": "@apollo/federation-internals", - "version": "2.5.6", + "version": "2.5.7", "license": "SEE LICENSE IN ./LICENSE", "dependencies": { "@types/uuid": "^9.0.0", @@ -17799,10 +17799,10 @@ }, "query-graphs-js": { "name": "@apollo/query-graphs", - "version": "2.5.6", + "version": "2.5.7", "license": "SEE LICENSE IN ./LICENSE", "dependencies": { - "@apollo/federation-internals": "2.5.6", + "@apollo/federation-internals": "2.5.7", "deep-equal": "^2.0.5", "ts-graphviz": "^1.5.4", "uuid": "^9.0.0" @@ -17816,11 +17816,11 @@ }, "query-planner-js": { "name": "@apollo/query-planner", - "version": "2.5.6", + "version": "2.5.7", "license": "SEE LICENSE IN ./LICENSE", "dependencies": { - "@apollo/federation-internals": "2.5.6", - "@apollo/query-graphs": "2.5.6", + "@apollo/federation-internals": "2.5.7", + "@apollo/query-graphs": "2.5.7", "@apollo/utils.keyvaluecache": "^2.1.0", "chalk": "^4.1.0", "deep-equal": "^2.0.5", @@ -17849,11 +17849,11 @@ }, "subgraph-js": { "name": "@apollo/subgraph", - "version": "2.5.6", + "version": "2.5.7", "license": "MIT", "dependencies": { "@apollo/cache-control-types": "^1.0.2", - "@apollo/federation-internals": "2.5.6" + "@apollo/federation-internals": "2.5.7" }, "engines": { "node": ">=14.15.0" diff --git a/query-graphs-js/CHANGELOG.md b/query-graphs-js/CHANGELOG.md index 2cf7ec9b5..e13af8b2f 100644 --- a/query-graphs-js/CHANGELOG.md +++ b/query-graphs-js/CHANGELOG.md @@ -1,5 +1,11 @@ # CHANGELOG for `@apollo/query-graphs` +## 2.5.7 +### Patch Changes + +- Updated dependencies []: + - @apollo/federation-internals@2.5.7 + ## 2.5.6 ### Patch Changes diff --git a/query-graphs-js/package.json b/query-graphs-js/package.json index 88cbd9e2f..e63787f2f 100644 --- a/query-graphs-js/package.json +++ b/query-graphs-js/package.json @@ -1,6 +1,6 @@ { "name": "@apollo/query-graphs", - "version": "2.5.6", + "version": "2.5.7", "description": "Apollo Federation library to work with 'query graphs'", "main": "dist/index.js", "types": "dist/index.d.ts", @@ -23,7 +23,7 @@ "node": ">=14.15.0" }, "dependencies": { - "@apollo/federation-internals": "2.5.6", + "@apollo/federation-internals": "2.5.7", "deep-equal": "^2.0.5", "ts-graphviz": "^1.5.4", "uuid": "^9.0.0" diff --git a/query-planner-js/CHANGELOG.md b/query-planner-js/CHANGELOG.md index 2e9b016df..0b332f7d2 100644 --- a/query-planner-js/CHANGELOG.md +++ b/query-planner-js/CHANGELOG.md @@ -1,5 +1,15 @@ # CHANGELOG for `@apollo/query-planner` +## 2.5.7 +### Patch Changes + + +- Fix query planning bug where keys or required fields can sometimes reach subgraphs with null values. ([#2805](https://github.com/apollographql/federation/issues/2805)) ([#2859](https://github.com/apollographql/federation/pull/2859)) + +- Updated dependencies []: + - @apollo/federation-internals@2.5.7 + - @apollo/query-graphs@2.5.7 + ## 2.5.6 ### Patch Changes diff --git a/query-planner-js/package.json b/query-planner-js/package.json index 2c44e946f..baea5e81c 100644 --- a/query-planner-js/package.json +++ b/query-planner-js/package.json @@ -1,6 +1,6 @@ { "name": "@apollo/query-planner", - "version": "2.5.6", + "version": "2.5.7", "description": "Apollo Query Planner", "author": "Apollo ", "main": "dist/index.js", @@ -25,8 +25,8 @@ "access": "public" }, "dependencies": { - "@apollo/federation-internals": "2.5.6", - "@apollo/query-graphs": "2.5.6", + "@apollo/federation-internals": "2.5.7", + "@apollo/query-graphs": "2.5.7", "@apollo/utils.keyvaluecache": "^2.1.0", "chalk": "^4.1.0", "deep-equal": "^2.0.5", diff --git a/subgraph-js/CHANGELOG.md b/subgraph-js/CHANGELOG.md index 5427f1fca..345f4188d 100644 --- a/subgraph-js/CHANGELOG.md +++ b/subgraph-js/CHANGELOG.md @@ -1,5 +1,11 @@ # CHANGELOG for `@apollo/subgraph` +## 2.5.7 +### Patch Changes + +- Updated dependencies []: + - @apollo/federation-internals@2.5.7 + ## 2.5.6 ### Patch Changes diff --git a/subgraph-js/package.json b/subgraph-js/package.json index 3af4c1b1d..2f27a4153 100644 --- a/subgraph-js/package.json +++ b/subgraph-js/package.json @@ -1,6 +1,6 @@ { "name": "@apollo/subgraph", - "version": "2.5.6", + "version": "2.5.7", "description": "Apollo Subgraph Utilities", "main": "dist/index.js", "types": "dist/index.d.ts", @@ -25,7 +25,7 @@ }, "dependencies": { "@apollo/cache-control-types": "^1.0.2", - "@apollo/federation-internals": "2.5.6" + "@apollo/federation-internals": "2.5.7" }, "peerDependencies": { "graphql": "^16.5.0" From 01315d053f1e0f5d214418ae82d876c39e721081 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 17 Nov 2023 08:21:43 -0700 Subject: [PATCH 34/42] Apply suggestions from code review Co-authored-by: Edward Huang <18322228+shorgi@users.noreply.github.com> --- docs/source/index.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 1bfb6bf1a..37a83a513 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -1,14 +1,14 @@ --- title: Introduction to Apollo Federation subtitle: Learn how to combine your GraphQL APIs into a unified supergraph -description: Learn how Apollo Federation can help you declaratively combine your GraphQL APIs into a unified, federated supergraph using microservices architecture +description: Learn how Apollo Federation can help you declaratively combine your GraphQL APIs into a unified, federated supergraph using a microservices architecture --- ## What is Apollo Federation? -**Apollo Federation** lets you combine multiple GraphQL APIs into a unified graph with a single entry point called the **router**. -Clients make requests to the router, which intelligently distributes them across your APIs and returns a unified response. -This architecture enables clients to interact with multiple services with a single request. +**Apollo Federation** lets you combine multiple GraphQL APIs into a unified graph, enabling a client to interact with multiple APIs through a single request. + +A client makes a request to the single entry point of the federated graph called the **router**. The router intelligently orchestrates and distributes a request across your APIs and returns a unified response. For a client, the request and response cycle of querying the router looks the same as querying any GraphQL server. ```mermaid graph LR; @@ -41,7 +41,7 @@ Beyond the generic benefits of using GraphQL and microservices architecture, Apo ### Preserve client performance -Sometimes, when an organization adopts GraphQL, multiple teams do so independently. Each team sets up a GraphQL service that provides the data used by that team. For example, a travel app may have separate GraphQL services for users, flights, and hotels: +A client may need to make multiple fetches when interacting with multiple non-federated GraphQL APIs. This can happen within an organization adopting GraphQL that has multiple teams developing independently. Each team sets up a GraphQL API that provides the data used by that team. For example, a travel app may have separate GraphQL services for users, flights, and hotels: ```mermaid graph RL; @@ -68,7 +68,7 @@ graph RL; class clients secondary; ``` -But if you expose multiple GraphQL APIs to clients, a client might need to communicate with _multiple_ APIs to fetch all the data it needs. With a single federated graph, you preserve a powerful advantage of GraphQL over traditional REST APIs: the ability to fetch all the data you need in a single request. +By exposing multiple GraphQL APIs to a client, it might need to communicate with _multiple_ APIs to fetch its data. With a single federated graph, you unlock a powerful advantage of GraphQL over traditional REST APIs: the ability to fetch all the data you need in a single request. ```mermaid graph LR; From beab6a4bdd44fa9386c0786d4389485c1bd7ea5f Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 17 Nov 2023 08:38:12 -0700 Subject: [PATCH 35/42] Apply suggestions from code review Co-authored-by: Edward Huang <18322228+shorgi@users.noreply.github.com> --- docs/source/index.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 37a83a513..fece6e0ec 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -28,6 +28,8 @@ No client-side configuration is required. ## Benefits of federation +### Microservices architecture + Apollo Federation lets API teams operate in a [microservices architecture](https://www.atlassian.com/microservices/microservices-architecture/microservices-vs-monolith) while exposing a unified GraphQL API to clients. Understanding these concepts can help you get the most out of federation. @@ -37,7 +39,6 @@ Apollo Federation lets API teams operate in a [microservices architecture](https -Beyond the generic benefits of using GraphQL and microservices architecture, Apollo Federation offers the following additional benefits. ### Preserve client performance From fc7f1fbe2b3be04beb790c81592b9c441cc13450 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 17 Nov 2023 08:44:38 -0700 Subject: [PATCH 36/42] Rework client benefit section --- docs/source/index.mdx | 23 +++++------------------ 1 file changed, 5 insertions(+), 18 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index fece6e0ec..ffa12a3de 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -22,10 +22,6 @@ graph LR; class clients secondary; ``` -For performance and security reasons, clients should only query the router, and only the router should query the constituent APIs. -For clients, the request and response cycle of querying the router looks the same as querying any GraphQL server. -No client-side configuration is required. - ## Benefits of federation ### Microservices architecture @@ -39,8 +35,7 @@ Apollo Federation lets API teams operate in a [microservices architecture](https - -### Preserve client performance +### Preserve client simplicity and performance A client may need to make multiple fetches when interacting with multiple non-federated GraphQL APIs. This can happen within an organization adopting GraphQL that has multiple teams developing independently. Each team sets up a GraphQL API that provides the data used by that team. For example, a travel app may have separate GraphQL services for users, flights, and hotels: @@ -69,7 +64,7 @@ graph RL; class clients secondary; ``` -By exposing multiple GraphQL APIs to a client, it might need to communicate with _multiple_ APIs to fetch its data. With a single federated graph, you unlock a powerful advantage of GraphQL over traditional REST APIs: the ability to fetch all the data you need in a single request. +By exposing multiple GraphQL APIs to a client, it might need to communicate with _multiple_ APIs to fetch its data. With a single federated graph, you preserve a powerful advantage of GraphQL over traditional REST APIs: the ability to fetch all the data you need in a single request. ```mermaid graph LR; @@ -91,7 +86,9 @@ graph LR; class clients secondary; ``` -Federation makes this possible because the router serves to orchestrate incoming operations, not to resolve each of them completely. +Federation makes this possible because the router serves to orchestrate incoming operations, not to resolve each of them completely. +Clients should only query the router, and only the router should query the constituent APIs. +No client-side configuration is required. ### Design schemas at scale @@ -163,13 +160,3 @@ Once you're ready to apply federation to your own APIs, these docs sections can ### Best practices Whether your supergraph implementation is already underway or just starting, you can use the [Supergraph Architecture Framework](https://saf.apollographql.com/) (SAF) to learn about best practices. The SAF includes an assessment you can take to quantify your supergraph's current state and identify areas for improvement. - - - - - - - - - - From f3c5c71e18c77785b0a35fcb9e9b0058ca7926b8 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 17 Nov 2023 08:47:56 -0700 Subject: [PATCH 37/42] Copyedit --- docs/source/index.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index ffa12a3de..38f42c8b7 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -6,9 +6,9 @@ description: Learn how Apollo Federation can help you declaratively combine your ## What is Apollo Federation? -**Apollo Federation** lets you combine multiple GraphQL APIs into a unified graph, enabling a client to interact with multiple APIs through a single request. +**Apollo Federation** lets you declaratively combine multiple GraphQL APIs into a unified graph. This enables clients to interact with multiple APIs through a single request. -A client makes a request to the single entry point of the federated graph called the **router**. The router intelligently orchestrates and distributes a request across your APIs and returns a unified response. For a client, the request and response cycle of querying the router looks the same as querying any GraphQL server. +A client makes a request to the single entry point of the federated graph called the **router**. The router intelligently orchestrates and distributes the request across your APIs and returns a unified response. For a client, the request and response cycle of querying the router looks the same as querying any GraphQL server. ```mermaid graph LR; @@ -37,7 +37,7 @@ Apollo Federation lets API teams operate in a [microservices architecture](https ### Preserve client simplicity and performance -A client may need to make multiple fetches when interacting with multiple non-federated GraphQL APIs. This can happen within an organization adopting GraphQL that has multiple teams developing independently. Each team sets up a GraphQL API that provides the data used by that team. For example, a travel app may have separate GraphQL services for users, flights, and hotels: +A client may need to make multiple fetches when interacting with multiple non-federated GraphQL APIs. This can happen within an organization adopting GraphQL that has multiple teams developing independently. Each team sets up a GraphQL API that provides the data used by that team. For example, a travel app may have separate GraphQL APIs for users, flights, and hotels: ```mermaid graph RL; @@ -123,7 +123,7 @@ graph LR; class clients secondary; ``` -Different subgraphs in the same supergraph can use different server languages and libraries as long as they are [federation-compatible](./building-supergraphs/supported-subgraphs/). +Different subgraphs in the same supergraph can use different server libraries as long as they are [federation-compatible](./building-supergraphs/supported-subgraphs/). @@ -159,4 +159,4 @@ Once you're ready to apply federation to your own APIs, these docs sections can ### Best practices -Whether your supergraph implementation is already underway or just starting, you can use the [Supergraph Architecture Framework](https://saf.apollographql.com/) (SAF) to learn about best practices. The SAF includes an assessment you can take to quantify your supergraph's current state and identify areas for improvement. +Whether your supergraph implementation is already underway or just starting, you can use the [Supergraph Architecture Framework](https://saf.apollographql.com/) (SAF) to learn about best practices. The SAF includes an assessment you can take to quantify your supergraph's current state and identify areas for improvement. \ No newline at end of file From e2cc96af52529f57f7044fe2f3a35e63e83e8fdc Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 17 Nov 2023 11:23:54 -0700 Subject: [PATCH 38/42] Apply suggestions from code review Co-authored-by: Dylan Anthony --- docs/source/index.mdx | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 38f42c8b7..17c85d75e 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -8,7 +8,7 @@ description: Learn how Apollo Federation can help you declaratively combine your **Apollo Federation** lets you declaratively combine multiple GraphQL APIs into a unified graph. This enables clients to interact with multiple APIs through a single request. -A client makes a request to the single entry point of the federated graph called the **router**. The router intelligently orchestrates and distributes the request across your APIs and returns a unified response. For a client, the request and response cycle of querying the router looks the same as querying any GraphQL server. +A client makes a request to the single entry point of the federated graph called the **router**. The router intelligently orchestrates and distributes the request across your APIs and returns a combined response. For a client, the request and response cycle of querying the router looks the same as querying any GraphQL server. ```mermaid graph LR; @@ -64,7 +64,7 @@ graph RL; class clients secondary; ``` -By exposing multiple GraphQL APIs to a client, it might need to communicate with _multiple_ APIs to fetch its data. With a single federated graph, you preserve a powerful advantage of GraphQL over traditional REST APIs: the ability to fetch all the data you need in a single request. +With a single federated graph, you preserve a powerful advantage of GraphQL over traditional REST APIs: the ability to fetch all the data you need in a single request. ```mermaid graph LR; @@ -86,7 +86,7 @@ graph LR; class clients secondary; ``` -Federation makes this possible because the router serves to orchestrate incoming operations, not to resolve each of them completely. +The router intelligently calls all the services it needs to complete a request, rather than simply forward them. Clients should only query the router, and only the router should query the constituent APIs. No client-side configuration is required. @@ -98,9 +98,8 @@ With Apollo Federation, clients can interact with the federated schema as if it ### Maintain a single API -With federation, every team maintaining a GraphQL API contributes directly to the overall federated schema. Instead of every team needing to manage its own graph layer, each team can be responsible for its slice of the API. When your entire organization contributes to the same graph, each team doesn't need to worry about maintaining its unique API. +With federation, every team contributes directly to the overall federated GraphQL schema. Each team can work independently without needing to maintain multiple API layers. This frees up your platform team to focus on the quality of your API, rather than keeping it up to date. -In this structure, the "graph team" might be a separate team dedicated to maintaining your router as part of the backend infrastructure, or it might be a "meta team" that includes representatives from other teams that maintain individual services. ## Next steps @@ -123,7 +122,7 @@ graph LR; class clients secondary; ``` -Different subgraphs in the same supergraph can use different server libraries as long as they are [federation-compatible](./building-supergraphs/supported-subgraphs/). +Different subgraphs in the same supergraph can use different server implementations and even different programming languages as long as they are [federation-compatible](./building-supergraphs/supported-subgraphs/). From a0fb5e4de019c6ef4abc664b717954aaa33d0e72 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 17 Nov 2023 13:03:39 -0700 Subject: [PATCH 39/42] Copyedit --- docs/source/index.mdx | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 17c85d75e..286f63842 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -6,9 +6,9 @@ description: Learn how Apollo Federation can help you declaratively combine your ## What is Apollo Federation? -**Apollo Federation** lets you declaratively combine multiple GraphQL APIs into a unified graph. This enables clients to interact with multiple APIs through a single request. +**Apollo Federation** lets you declaratively combine multiple GraphQL APIs into a single, federated graph. This federated graph enables clients to interact with multiple APIs through a single request. -A client makes a request to the single entry point of the federated graph called the **router**. The router intelligently orchestrates and distributes the request across your APIs and returns a combined response. For a client, the request and response cycle of querying the router looks the same as querying any GraphQL server. +A client makes a request to the single entry point of the federated graph called the **router**. The router intelligently orchestrates and distributes the request across your APIs and returns a unified response. For a client, the request and response cycle of querying the router looks the same as querying any GraphQL server. ```mermaid graph LR; @@ -37,7 +37,7 @@ Apollo Federation lets API teams operate in a [microservices architecture](https ### Preserve client simplicity and performance -A client may need to make multiple fetches when interacting with multiple non-federated GraphQL APIs. This can happen within an organization adopting GraphQL that has multiple teams developing independently. Each team sets up a GraphQL API that provides the data used by that team. For example, a travel app may have separate GraphQL APIs for users, flights, and hotels: +A client may need to make multiple requests when interacting with multiple non-federated GraphQL APIs. This can happen when an organization adopting GraphQL has multiple teams developing APIs independently. Each team sets up a GraphQL API that provides the data used by that team. For example, a travel app may have separate GraphQL APIs for users, flights, and hotels: ```mermaid graph RL; @@ -86,8 +86,8 @@ graph LR; class clients secondary; ``` -The router intelligently calls all the services it needs to complete a request, rather than simply forward them. -Clients should only query the router, and only the router should query the constituent APIs. +The router intelligently calls all the APIs it needs to complete requests rather than simply forwarding them. +For performance and security reasons, clients should only query the router, and only the router should query the constituent APIs. No client-side configuration is required. ### Design schemas at scale @@ -98,7 +98,7 @@ With Apollo Federation, clients can interact with the federated schema as if it ### Maintain a single API -With federation, every team contributes directly to the overall federated GraphQL schema. Each team can work independently without needing to maintain multiple API layers. This frees up your platform team to focus on the quality of your API, rather than keeping it up to date. +With federation, every team contributes directly to the overall federated GraphQL schema. Each team can work independently without needing to maintain multiple API layers. This frees your platform team to focus on the quality of your API rather than keeping it up to date. ## Next steps @@ -135,7 +135,7 @@ Different subgraphs in the same supergraph can use different server implementati Depending on your goals, you have several options for learning more about federation: - If you're new to federated architecture, this [overview article](https://graphql.com/learn/federated-architecture/) can familiarize the concepts. -- If you'd like to recap key concepts of Apollo Federation, the video below gives a great overview. +- If you'd like to recap the key concepts of Apollo Federation, the video below gives a great overview. @@ -154,8 +154,4 @@ Once you're ready to apply federation to your own APIs, these docs sections can - Reference materials for: - [Performance considerations](./performance/caching) - [Debugging and metrics](./errors) - - [Subgraph specifications](./building-supergraphs/router) for federation-compatibility - -### Best practices - -Whether your supergraph implementation is already underway or just starting, you can use the [Supergraph Architecture Framework](https://saf.apollographql.com/) (SAF) to learn about best practices. The SAF includes an assessment you can take to quantify your supergraph's current state and identify areas for improvement. \ No newline at end of file + - [Subgraph specifications](./building-supergraphs/router) for federation-compatibility \ No newline at end of file From ff36601be9b51ac457349cad8b041329c9349003 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 17 Nov 2023 13:51:59 -0700 Subject: [PATCH 40/42] Add Cspell ignoreRegExpList for YoutubeIds --- .cspell/cspell.yml | 3 ++- docs/source/index.mdx | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.cspell/cspell.yml b/.cspell/cspell.yml index cbf546230..51916796b 100644 --- a/.cspell/cspell.yml +++ b/.cspell/cspell.yml @@ -34,10 +34,11 @@ overrides: - filename: '**/CHANGELOG*.md' ignoreRegExpList: - "@[-\\w]+" - # Ignore the targets of links in Markdown/MDX files. + # Ignore the targets of links and YouTube IDs in Markdown/MDX files. - filename: '**/*.md*' ignoreRegExpList: - "\\]\\([^)]+\\)" + - "youTubeID=.+/>" # Ignore user and repo names in GitHub links to supported subgraph libraries. - filename: '**/supported-subgraphs.md' ignoreRegExpList: diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 286f63842..b48ce3fa1 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -139,7 +139,7 @@ Depending on your goals, you have several options for learning more about federa - + From c0e2f867ff8f72743e11f4873f4ea27d76ef91fc Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 17 Nov 2023 14:05:39 -0700 Subject: [PATCH 41/42] Correct links --- docs/source/index.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index b48ce3fa1..a31c0c68e 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -139,7 +139,7 @@ Depending on your goals, you have several options for learning more about federa - + @@ -150,7 +150,7 @@ Depending on your goals, you have several options for learning more about federa Once you're ready to apply federation to your own APIs, these docs sections can help you get started: - Conceptual overview of [Federated Schemas](./federated-types/overview) -- [Guide on using Apollo GraphOS](./managed-federation) to automate and manage deployments of your federated schemas (this is also known as **Managed Federation**) +- [Guide on using Apollo GraphOS](./managed-federation/overview) to automate and manage deployments of your federated schemas (this is also known as **Managed Federation**) - Reference materials for: - [Performance considerations](./performance/caching) - [Debugging and metrics](./errors) From 2c9187974cac5bf6d3989f93faf9a7b508a882e5 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Fri, 17 Nov 2023 14:14:01 -0700 Subject: [PATCH 42/42] Change relative link --- docs/source/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/index.mdx b/docs/source/index.mdx index a31c0c68e..5b4dbf485 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -30,7 +30,7 @@ Apollo Federation lets API teams operate in a [microservices architecture](https -- Learn more about the [considerations and benefits of GraphQL](/intro/benefits/). +- Learn more about the [considerations and benefits of GraphQL](https://www.apollographql.com/docs/intro/benefits). - Learn more about the [considerations and benefits of microservices architecture](https://aws.amazon.com/compare/the-difference-between-monolithic-and-microservices-architecture/).