From 857363c64c1e9a40bb1b64b25fb0eae3204eda96 Mon Sep 17 00:00:00 2001 From: Stephen Barlow Date: Thu, 30 Jun 2022 15:54:37 -0700 Subject: [PATCH] Clarify required version for graphql library, plus other edits --- docs/source/federated-types/composition.mdx | 20 ++++++------------- docs/source/federated-types/overview.mdx | 6 +++--- .../federation-2/moving-to-federation-2.mdx | 17 +++++++++------- docs/source/gateway.mdx | 3 ++- docs/source/index.mdx | 4 ++-- docs/source/other-servers.md | 3 ++- docs/source/subgraphs.mdx | 5 +++-- 7 files changed, 28 insertions(+), 30 deletions(-) diff --git a/docs/source/federated-types/composition.mdx b/docs/source/federated-types/composition.mdx index 3604b2e3b..36115f142 100644 --- a/docs/source/federated-types/composition.mdx +++ b/docs/source/federated-types/composition.mdx @@ -30,15 +30,7 @@ The [Rover CLI](https://www.apollographql.com/docs/rover/) supports a `supergrap rover supergraph compose --config ./supergraph-config.yaml ``` -> ⚠️ **Important:** To perform Federation 2 composition with Rover, the YAML `--config` file you provide must include the following line: -> -> ```yaml title="supergraph-config.yaml" -> federation_version: 2 -> ``` -> -> Otherwise, Rover uses Federation 1 composition. - -To learn how to install Rover and use this command, see the [Quickstart](../quickstart/setup/#1-install-the-rover-cli). +To learn how to install Rover and use this command, see the [quickstart](../quickstart/setup/#1-install-the-rover-cli). ### Automatically with managed federation @@ -62,7 +54,7 @@ graph LR; class uplink secondary; ``` -To learn how to perform composition with managed federation, see the [Quickstart](../quickstart/studio-composition/). +To learn how to perform composition with managed federation, see the [quickstart](../quickstart/studio-composition/). ## Breaking composition @@ -253,7 +245,7 @@ This is a useful solution when a type corresponds closely to an entry in a data If a particular GraphQL type is defined _differently_ by different subgraphs, composition uses one of two strategies to merge those definitions: **union** or **intersection**. -* **Union**: The supergraph schema includes _all_ parts of _all_ subgraph definitions for the type. +* **Union**: The supergraph schema includes _all_ parts of _all_ subgraph definitions for the type. * **Intersection:** The supergraph schema includes _only_ the parts of the type that are present in _every_ subgraph that defines the type. The merging strategy that composition uses for a particular type depends on the type, as described below. @@ -373,7 +365,7 @@ As you can see, the supergraph schema includes only the input fields and argumen ### Enums -Composition might use the union strategy _or_ the intersection strategy when merging enum type definitions, _depending on how the enum is used_. +Composition might use the union strategy _or_ the intersection strategy when merging enum type definitions, _depending on how the enum is used_. ```mermaid graph TB; @@ -420,7 +412,7 @@ enum Color { } ``` -If you use an enum as _either_ a field argument or an input field's return type in at least one of your subgraphs, composition merges using the [intersection strategy](#merging-types-from-multiple-subgraphs). +If you use an enum as _either_ a field argument or an input field's return type in at least one of your subgraphs, composition merges using the [intersection strategy](#merging-types-from-multiple-subgraphs). Let's say we add a new field to Subgraph A that uses our `Color` enum as a field argument: @@ -495,4 +487,4 @@ enum Color { type ColorQuery { avatar(borderColor: Color): String } -``` \ No newline at end of file +``` diff --git a/docs/source/federated-types/overview.mdx b/docs/source/federated-types/overview.mdx index 45b075fee..14ae189cd 100644 --- a/docs/source/federated-types/overview.mdx +++ b/docs/source/federated-types/overview.mdx @@ -3,7 +3,7 @@ title: Federated schemas description: Overview --- -A federated graph uses multiple "types" of GraphQL schemas: +A federated supergraph uses multiple "types" of GraphQL schemas: ```mermaid graph TB; @@ -21,9 +21,9 @@ graph TB; * **Subgraph schemas.** Each **subgraph** has a distinct schema that indicates _which_ types and fields of your composed **supergraph** it can resolve. * These are the only schemas that your teams define manually. -* **Supergraph schema.** This schema combines all of the types and fields from your subgraph schemas, _plus_ some Federation-specific information that tells your gateway which subgraphs can resolve which fields. +* **Supergraph schema.** This schema combines all of the types and fields from your subgraph schemas, _plus_ some federation-specific information that tells your gateway which subgraphs can resolve which fields. * This schema is the result of performing [composition](./composition/) on your collection of subgraph schemas. -* **API schema.** This schema is like the supergraph schema, but it _omits_ types, fields, and directives that are considered "machinery" and are not part of your public API (this includes Federation-specific information). +* **API schema.** This schema is similar to the supergraph schema, but it _omits_ federation-specific types, fields, and directives that are considered "machinery" and are not part of your public API. * This is the schema that your gateway exposes to clients, who don't need to know internal implementation details about your graph. Let's look at an example! diff --git a/docs/source/federation-2/moving-to-federation-2.mdx b/docs/source/federation-2/moving-to-federation-2.mdx index 9f08ba926..3efd3be02 100644 --- a/docs/source/federation-2/moving-to-federation-2.mdx +++ b/docs/source/federation-2/moving-to-federation-2.mdx @@ -7,7 +7,7 @@ description: Upgrade your supergraph incrementally at any pace You can (and should!) move your Apollo Federation 1 supergraph to Federation 2 **incrementally**, one component at a time. Your supergraph will work as expected after each step in the process, even if some of your subgraphs continue using Federation 1 schemas. -Each individual step of moving your supergraph has its own benefits, so it's useful to complete as many steps as you're ready to complete. You can always complete the rest later. +Each individual step of moving your supergraph has its own benefits, so it's useful to complete as many steps as you're ready to complete. You can always finish the rest later. Here are the three steps for moving to Federation 2: @@ -18,7 +18,8 @@ graph LR; composition --> subgrahs(Update individual subgraphs); ``` -1. Update your gateway to a version that supports Federation 2 (or swap out your gateway for the [Apollo Router](/router/)). +1. Update your gateway to a version that supports Federation 2. + * Alternatively, you can swap out your Node.js gateway for the [Apollo Router](/router/). 2. Begin composing your supergraph schema with Federation 2 composition logic. 3. Update your individual subgraphs to use Federation 2 features and directives. @@ -26,15 +27,17 @@ Steps 1 and 2 are quick, and it's straightforward to reverse them if you need to > If you encounter an issue while moving your supergraph to Federation 2, please describe the issue in the [community forums](https://community.apollographql.com/). -## Step 1: Update `@apollo/gateway` +## Step 1: Update your gateway -The `@apollo/gateway` library supports Federation 2 supergraph schemas in version `2.0.0` and later. You can install the latest version in your gateway project with the following command: +The `@apollo/gateway` library supports Federation 2 supergraph schemas in version `2.0.0` and later. These versions of `@apollo/gateway` require version `16.0.0` or later of the `graphql` library. + +You can install updated versions of these libraries in your gateway project with the following command: ```bash -npm install @apollo/gateway +npm install @apollo/gateway graphql ``` -Alternatively, you can _swap out_ your supergraph's gateway for the **Apollo Router**, a high-performance graph router implemented in Rust. [See the docs.](/router/migrating-from-gateway/) +Alternatively, you can _swap out_ your Node.js gateway for the **Apollo Router**, a high-performance graph router implemented in Rust. [See the docs.](/router/migrating-from-gateway/) > Both `@apollo/gateway` v2.x _and_ the Apollo Router support Federation 1! You can update to either without making any other changes, and your Federation 1 supergraph will work as expected. @@ -62,7 +65,7 @@ Open the Settings page for the variant you want to move to Federation 2, then se Click **Edit Configuration**. The following dialog appears: -Edit supported directives in Studio +Edit supported directives in Studio In the Federation Version dropdown, select **Federation 2** and click **Save**. diff --git a/docs/source/gateway.mdx b/docs/source/gateway.mdx index 7c39b66c9..583a61101 100644 --- a/docs/source/gateway.mdx +++ b/docs/source/gateway.mdx @@ -1,8 +1,9 @@ --- title: Implementing the gateway +description: In a federated supergraph --- -> 📣 **The Apollo Router** is a new high-performance graph router written in Rust that is currently in preview. You can try out the Apollo Router in place of the Apollo Gateway documented here. [See the documentation.](https://www.apollographql.com/docs/router/) +> 📣 **The Apollo Router** is a new high-performance graph router written in Rust. You can use the Apollo Router in place of the Node.js gateway documented here. [See the documentation.](https://www.apollographql.com/docs/router/) After you set up at least one federation-ready [subgraph](./subgraphs/), you can configure a **gateway** to sit in front of your subgraphs. The gateway serves as the entry point to your supergraph, and it executes incoming operations across one or more of your subgraphs. diff --git a/docs/source/index.mdx b/docs/source/index.mdx index d2ece8cb8..f8d1add41 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -12,7 +12,7 @@ import FederationArchitecture from '../shared/diagrams/federation-architecture.m > > Docs for Federation 1 are [available here](/federation/v1/). -**Apollo Federation** is a powerful, open architecture that helps you create a **unified supergraph** that combines multiple GraphQL APIs: +**Apollo Federation** is a powerful, open architecture for creating a **supergraph** that combines multiple GraphQL APIs: ```mermaid graph BT; @@ -127,7 +127,7 @@ graph BT; * The gateway is one of the following: * An instance of Apollo Server using special extensions from the [`@apollo/gateway`](./api/apollo-gateway) library - * An instance of [the Apollo Router](https://www.apollographql.com/docs/router/), a highly performant Rust-based graph router that is currently in public preview + * An instance of [the Apollo Router](https://www.apollographql.com/docs/router/): a high-performance, Rust-based graph router * Subgraphs can run Apollo Server using special extensions from the [`@apollo/subgraph`](./api/apollo-subgraph) library, _or_ they can run any other [subgraph-compatible GraphQL server](./other-servers/). Different subgraphs in the same supergraph can even use different server libraries. diff --git a/docs/source/other-servers.md b/docs/source/other-servers.md index c1cea02f4..527f54c61 100644 --- a/docs/source/other-servers.md +++ b/docs/source/other-servers.md @@ -1,8 +1,9 @@ --- title: Subgraph-compatible server libraries +description: For use in a federated supergraph --- -The following open-source GraphQL server libraries support acting as a subgraph in a federated graph, and their support is tracked in Apollo's [subgraph compatibility repository](https://github.com/apollographql/apollo-federation-subgraph-compatibility). Check out the repository for details on the compatibility tests listed in the table below. +The following open-source GraphQL server libraries support acting as a subgraph in a federated supergraph, and their support is tracked in Apollo's [subgraph compatibility repository](https://github.com/apollographql/apollo-federation-subgraph-compatibility). Check out the repository for details on the compatibility tests listed in the table below. > To add a library to this list, feel free to open an [issue](https://github.com/apollographql/apollo-federation-subgraph-compatibility/issues) or check out the [Apollo Federation Library Maintainers Implementation Guide](https://github.com/apollographql/apollo-federation-subgraph-compatibility/blob/main/CONTRIBUTORS.md) to learn how to submit a PR for your library! diff --git a/docs/source/subgraphs.mdx b/docs/source/subgraphs.mdx index c3d7c485a..116578d8d 100644 --- a/docs/source/subgraphs.mdx +++ b/docs/source/subgraphs.mdx @@ -1,12 +1,13 @@ --- title: Implementing subgraphs +description: In a federated supergraph --- import FederationArchitecture from '../shared/diagrams/federation-architecture.mdx'; This article demonstrates how to create a **subgraph** for a federated supergraph using Node.js and Apollo Server. -> To create a subgraph using a different language and/or framework, see the list of [subgraph-compatible libraries](./other-servers/). Note that not all libraries provide full support for Federation features. +> To create a subgraph using a different language and/or framework, see the list of [subgraph-compatible libraries](./other-servers/). Note that not all listed libraries provide full support for Federation features. ## Defining a subgraph @@ -202,7 +203,7 @@ Because of the power and flexibility of the [`Query._entities` and `Query._servi -Make sure to implement any necessary firewall rules, access control lists, or other measures to ensure that individual subgraphs can be accessed _only_ via the gateway. We also recommend that subgraphs do not enable CORS (or at least do not use the wildcard `access-control-allow-origin: *` header) so that attackers cannot use a victim's browser to access the subgraph directly. With Apollo Server, this means disabling the default "wildcard" CORS policy which is appropriate for most publicly-exposed servers but not for inaccessible servers. See [the Apollo Server CORS documentation](/apollo-server/security/cors/#choosing-cors-options-for-your-project) for more details. +Make sure to implement any necessary firewall rules, access control lists, or other measures to ensure that individual subgraphs can be accessed _only_ via the gateway. We also recommend that subgraphs do not enable CORS (or at least do not use the wildcard `access-control-allow-origin: *` header) so that attackers cannot exploit a user's browser to access the subgraph directly. With Apollo Server, this means disabling the default "wildcard" CORS policy which is appropriate for most publicly-exposed servers but not for inaccessible servers. See [the Apollo Server CORS documentation](/apollo-server/security/cors/#choosing-cors-options-for-your-project) for more details. ## Subgraph-specific fields