diff --git a/composition-js/src/genHintDoc.ts b/composition-js/src/genHintDoc.ts index bc6780932..56bd70366 100644 --- a/composition-js/src/genHintDoc.ts +++ b/composition-js/src/genHintDoc.ts @@ -5,7 +5,7 @@ const header = `--- title: Composition hints --- -When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./subgraphs/) into a supergraph schema, the composition process might output **hints** that provide additional information about the result. Hints are primarily informative and _do not_ necessarily indicate that a problem needs to be fixed. +When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process might output **hints** that provide additional information about the result. Hints are primarily informative and _do not_ necessarily indicate that a problem needs to be fixed. Hints are categorized under the following levels: diff --git a/docs/source/_redirects b/docs/source/_redirects index 9a56f6c99..752d89903 100644 --- a/docs/source/_redirects +++ b/docs/source/_redirects @@ -1,5 +1,8 @@ -/gateway/ /docs/federation/router/ -/other-servers/ /docs/federation/supported-subgraphs/ +/subgraphs/ /docs/federation/building-supergraphs/subgraphs-apollo-server/ +/gateway/ /docs/federation/building-supergraphs/router/ +/router/ /docs/federation/building-supergraphs/router/ +/supported-subgraphs/ /docs/federation/building-supergraphs/supported-subgraphs/ +/other-servers/ /docs/federation/building-supergraphs/supported-subgraphs/ /federation-spec/ /docs/federation/subgraph-spec/ /v2/* /docs/federation/:splat diff --git a/docs/source/api/apollo-gateway.mdx b/docs/source/api/apollo-gateway.mdx index 46a14b598..5a96ed7a3 100644 --- a/docs/source/api/apollo-gateway.mdx +++ b/docs/source/api/apollo-gateway.mdx @@ -9,7 +9,7 @@ This API reference documents the exports from the `@apollo/gateway` package. ## `class ApolloGateway` The core class of Apollo Server's federated gateway implementation. For an -example of using `ApolloGateway`, see [The gateway](../gateway/). +example of using `ApolloGateway`, see [The graph router](../building-supergraphs/router/). ### Methods @@ -585,7 +585,7 @@ The details of the `fetch` response sent by the subgraph. ## `class IntrospectAndCompose` -> ⚠️ **We strongly recommend _against_ using `IntrospectAndCompose` in production.** For details, see [Limitations of `IntrospectAndCompose`](../router#limitations-of-introspectandcompose). +> ⚠️ **We strongly recommend _against_ using `IntrospectAndCompose` in production.** For details, see [Limitations of `IntrospectAndCompose`](../building-supergraphs/router#limitations-of-introspectandcompose). `IntrospectAndCompose` is a development tool for fetching and composing subgraph SDL into a supergraph for your gateway. Given a list of subgraphs and their URLs, `IntrospectAndCompose` will issue queries for their SDL, compose them into a supergraph, and provide that supergraph to the gateway. It can also be configured to update via polling and perform subgraph health checks to ensure that supergraphs are updated safely. `IntrospectAndCompose` implements the `SupergraphManager` interface and is passed in to `ApolloGateway`'s `supergraphSdl` constructor option. diff --git a/docs/source/api/apollo-subgraph.mdx b/docs/source/api/apollo-subgraph.mdx index 1865d4b37..5cc65d2bb 100644 --- a/docs/source/api/apollo-subgraph.mdx +++ b/docs/source/api/apollo-subgraph.mdx @@ -18,7 +18,7 @@ const server = new ApolloServer({ }); ``` -Used when [defining a subgraph](../subgraphs/#defining-a-subgraph) in a federated graph. +Used when [defining a subgraph](../building-supergraphs/subgraphs-apollo-server/#defining-a-subgraph) in a federated graph. Each schema module is an object with the following format: diff --git a/docs/source/router.mdx b/docs/source/building-supergraphs/router.mdx similarity index 93% rename from docs/source/router.mdx rename to docs/source/building-supergraphs/router.mdx index 63e0bbb5f..d6c8ad48b 100644 --- a/docs/source/router.mdx +++ b/docs/source/building-supergraphs/router.mdx @@ -5,7 +5,7 @@ description: The entry point to your federated supergraph import FederationArchitecture from '../shared/diagrams/federation-architecture.mdx'; -After you set up at least one federation-ready [subgraph](./subgraphs/), you can configure a **graph router** (also known as a gateway) to sit in front of your subgraphs. The router serves as the entry point to your supergraph, and it executes incoming operations across one or more of your subgraphs: +After you set up at least one federation-ready [subgraph](./subgraphs-overview/), you can configure a **graph router** (also known as a gateway) to sit in front of your subgraphs. The router serves as the entry point to your supergraph, and it executes incoming operations across one or more of your subgraphs: @@ -15,7 +15,7 @@ Apollo actively supports two options for your graph router: * **The Apollo Router (recommended):** This is a high-performance, precompiled Rust binary. * [Go to the Apollo Router docs.](/router/quickstart/) - * [See the federation quickstart](./quickstart/setup/) (which uses the Apollo Router). + * [See the federation quickstart](../quickstart/setup/) (which uses the Apollo Router). * **Apollo Server:** Apollo Server can act as your graph router via the [`@apollo/gateway`](https://www.npmjs.com/package/@apollo/gateway) extension library. **We recommend starting with the Apollo Router.** It's faster to configure, it's more performant (especially with high request loads), and it rarely requires writing custom code. @@ -40,7 +40,7 @@ Create a new Node.js project with `npm init`, then install the necessary package npm install @apollo/gateway apollo-server graphql ``` -The `@apollo/gateway` package includes the [`ApolloGateway` class](./api/apollo-gateway/). To configure Apollo Server to act as a graph router, you pass an instance of `ApolloGateway` to the `ApolloServer` constructor, like so: +The `@apollo/gateway` package includes the [`ApolloGateway` class](../api/apollo-gateway/). To configure Apollo Server to act as a graph router, you pass an instance of `ApolloGateway` to the `ApolloServer` constructor, like so: ```js {7-11,13-16} title="index.js" const { ApolloServer, gql } = require('apollo-server'); @@ -67,11 +67,11 @@ server.listen().then(({ url }) => { ### Composing the supergraph schema -In the above example, we provide the `supergraphSdl` option to the `ApolloGateway` constructor. This is the string representation of our [supergraph schema](./federated-types/overview/#supergraph-schema), which is composed from all of our subgraph schemas. +In the above example, we provide the `supergraphSdl` option to the `ApolloGateway` constructor. This is the string representation of our [supergraph schema](../federated-types/overview/#supergraph-schema), which is composed from all of our subgraph schemas. -To learn how to compose your supergraph schema, see [Supported methods](./federated-types/composition/#supported-methods). +To learn how to compose your supergraph schema, see [Supported methods](../federated-types/composition/#supported-methods). -> In production, we strongly recommend running the gateway in a **managed mode** with Apollo Studio, which enables your gateway to update its configuration without a restart. For details, see [Setting up managed federation](https://www.apollographql.com/docs/studio/managed-federation/setup/). +> In production, we strongly recommend running the gateway in a **managed mode** with Apollo Studio, which enables your gateway to update its configuration without a restart. For details, see [Setting up managed federation](/studio/managed-federation/setup/). On startup, the gateway processes your `supergraphSdl`, which includes routing information for your subgraphs. It then begins accepting incoming requests and creates query plans for them that execute across one or more subgraphs. @@ -199,7 +199,7 @@ Each item in the `subgraphs` array is an object that specifies the `name` and `u On startup, the gateway fetches each subgraph's schema from its `url` and composes those schemas into a supergraph schema. It then begins accepting incoming requests and creates query plans for them that execute across one or more subgraphs. -Additional configuration options can be found in the [`IntrospectAndCompose` API documentation](./api/apollo-gateway#class-introspectandcompose). +Additional configuration options can be found in the [`IntrospectAndCompose` API documentation](../api/apollo-gateway#class-introspectandcompose). However, `IntrospectAndCompose` has important [limitations](#limitations-of-introspectandcompose). @@ -207,7 +207,7 @@ However, `IntrospectAndCompose` has important [limitations](#limitations-of-intr The `IntrospectAndCompose` option can sometimes be helpful for local development, but it's strongly discouraged for any other environment. Here are some reasons why: -* **Composition might fail.** With `IntrospectAndCompose`, your gateway performs composition dynamically on startup, which requires network communication with each subgraph. If composition fails, your gateway [throws errors](./errors/) and experiences unplanned downtime. +* **Composition might fail.** With `IntrospectAndCompose`, your gateway performs composition dynamically on startup, which requires network communication with each subgraph. If composition fails, your gateway [throws errors](../errors/) and experiences unplanned downtime. * With the static or dynamic `supergraphSdl` configuration, you instead provide a supergraph schema that has _already_ been composed successfully. This prevents composition errors and enables faster startup. * **Gateway instances might differ.** If you deploy multiple instances of your gateway _while_ deploying updates to your subgraphs, your gateway instances might fetch different schemas from the _same_ subgraph. This can result in sporadic composition failures or inconsistent supergraph schemas between instances. * When you deploy multiple instances with `supergraphSdl`, you provide the exact same static artifact to each instance, enabling more predictable behavior. @@ -387,11 +387,11 @@ server.listen().then(({ url }) => { > In this example, multiple calls to `didReceiveResponse` are `push`ing a value onto the shared `context.serverIds` array. The order of these calls cannot be guaranteed. If you write logic that modifies the shared `context` object, make sure that modifications are not destructive, and that the order of modifications doesn't matter. -To learn more about `buildService` and `RemoteGraphQLDataSource`, see the [API docs](./api/apollo-gateway/). +To learn more about `buildService` and `RemoteGraphQLDataSource`, see the [API docs](../api/apollo-gateway/). ## Custom directive support -The `@apollo/gateway` library supports the use of custom [directives](https://www.apollographql.com/docs/apollo-server/schema/directives/) in your subgraph schemas. This support differs depending on whether a given directive is a **type system directive** or an **executable directive**. +The `@apollo/gateway` library supports the use of custom [directives](/apollo-server/schema/directives/) in your subgraph schemas. This support differs depending on whether a given directive is a **type system directive** or an **executable directive**. ### Type system directives @@ -410,7 +410,7 @@ type ExampleType { } ``` -The gateway strips all definitions _and_ uses of type system directives from your graph's [API schema](./federated-types/overview/#api-schema). This has no effect on your subgraph schemas, which retain this information. +The gateway strips all definitions _and_ uses of type system directives from your graph's [API schema](../federated-types/overview/#api-schema). This has no effect on your subgraph schemas, which retain this information. Effectively, the gateway supports type system directives by _ignoring_ them, making them the responsibility of the subgraphs that define them. diff --git a/docs/source/subgraphs.mdx b/docs/source/building-supergraphs/subgraphs-apollo-server.mdx similarity index 65% rename from docs/source/subgraphs.mdx rename to docs/source/building-supergraphs/subgraphs-apollo-server.mdx index fc01fb70f..14e67cf00 100644 --- a/docs/source/subgraphs.mdx +++ b/docs/source/building-supergraphs/subgraphs-apollo-server.mdx @@ -2,15 +2,13 @@ title: Implementing a subgraph with Apollo Server --- -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 [Federation-compatible subgraph implementations](./supported-subgraphs/). Note that not all listed libraries provide full support for Federation features. +> To create a subgraph using a different language and/or framework, see the list of [Federation-compatible subgraph implementations](./supported-subgraphs/). Note that not all listed libraries support _all_ Federation features. ## Defining a subgraph -> To be part of a supergraph, a subgraph must conform to the [Apollo Federation subgraph specification](./subgraph-spec/), which exposes the subgraph's capabilities to your graph router, as well as to tools like Apollo Studio. +> To be part of a supergraph, a subgraph must conform to the [Apollo Federation subgraph specification](../subgraph-spec/), which exposes the subgraph's capabilities to your graph router, as well as to tools like Apollo Studio. Converting an existing monolithic graph into a single subgraph is a convenient first step in building a federated supergraph. To start, here's a *non-federated* Apollo Server setup: @@ -66,7 +64,7 @@ const { buildSubgraphSchema } = require('@apollo/subgraph'); ### 2. Opt in to Federation 2 -For a subgraph to use [new features in Federation 2](./federation-2/new-in-federation-2/), its schema needs to include the following `extend schema` definition: +For a subgraph to use [new features in Federation 2](../federation-2/new-in-federation-2/), its schema needs to include the following `extend schema` definition: ```js {2-4} const typeDefs = gql` @@ -87,13 +85,13 @@ extend schema This definition enables the schema to use Federation 2 features. Without it, Federation 2 composition assumes that a subgraph is using Federation 1, which sets certain defaults for backward compatibility. -> As you begin using more [federation-specific directives](./federated-types/federated-directives) beyond `@key` and `@shareable`, you'll need to add those directives to the `import` array shown above. +> As you begin using more [federation-specific directives](../federated-types/federated-directives) beyond `@key` and `@shareable`, you'll need to add those directives to the `import` array shown above. ### 3. Define an entity > Entities aren't _required_ in a subgraph, but they're a core building block of a federated supergraph, so it's good to get some practice defining them. -As part of our federated architecture, we want _other_ subgraphs to be able to contribute fields to the `User` type. To enable this, we add the `@key` directive to the `User` type's definition to designate it as an [entity](./entities/): +As part of our federated architecture, we want _other_ subgraphs to be able to contribute fields to the `User` type. To enable this, we add the `@key` directive to the `User` type's definition to designate it as an [entity](../entities/): ```js {10} title="index.js" const typeDefs = gql` @@ -133,7 +131,7 @@ const resolvers = { (This example requires defining the `fetchUserById` function to obtain the appropriate `User` from our backing data store.) -> [Learn more about entities.](./entities/) +> [Learn more about entities.](../entities/) ### 4. Generate the subgraph schema @@ -196,96 +194,6 @@ server.listen(4001).then(({ url }) => { }); ``` -## Securing your subgraphs - -Because of the power and flexibility of the [`Query._entities` and `Query._service` fields](#subgraph-specific-fields), your subgraphs should **not** be directly accessible by clients. Instead, only your graph router should have access to your subgraphs. Clients then communicate with the router: - - - -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 router. - -### Disabling CORS - -We recommend that subgraphs do not enable CORS (or at least do not use the wildcard `access-control-allow-origin: *` header). This prevents attackers from exploiting a user's browser to access a subgraph directly. - -For Apollo Server subgraphs, you need to disable the default wildcard CORS policy (which is appropriate for many publicly-exposed servers but not for inaccessible servers like subgraphs). For details, see the [Apollo Server CORS documentation](/apollo-server/security/cors/#choosing-cors-options-for-your-project). - -## Subgraph-specific fields - -When you [generate your subgraph schema](#4-generate-the-subgraph-schema), some federation-specific definitions are automatically added to it. In addition to directive definitions like `@key`, the most useful of these definitions for debugging are two fields of the `Query` type: `_service` and `_entities`: - -```graphql -type Query { - # ...your field definitions... - - # Added automatically - _service: _Service! - _entities(representations: [_Any!]!): [_Entity]! -} -``` - -### `Query._service` - -This field returns a `_Service` object with one field of its own: `sdl`. You can query it like so: - -```graphql -query GetSubgraphSchema { - _service { - sdl - } -} -``` - -The `sdl` field returns your subgraph's schema as an SDL string. This field has a couple of important differences from a standard [introspection query](https://graphql.org/learn/introspection/) that a tool like Apollo Sandbox uses: - -* Unlike introspection, the `sdl` field is _not_ disabled by default in production environments (this is safe if you properly [secure your subgraph](#securing-your-subgraphs)). -* Unlike introspection, the `sdl` field's returned string includes federation-specific directives like `@key`. - -### `Query._entities` - -> [Learn about entities](./entities/) if you haven't yet. - -This field takes a list of **entity representations** and returns a list of corresponding entities. - -> Whenever one subgraph references _another_ subgraph's entity, it uses an **entity representation** to do so. An entity representation is an object that includes _only_ the entity's `__typename` and the fields in the entity's `@key`. - -```graphql -_entities(representations: [_Any!]!): [_Entity]! -``` - -* The `_Any` type is a special scalar that enables you to provide entity representations of any valid shape. -* The `_Entity` type is a generated [union type](https://www.apollographql.com/docs/apollo-server/schema/unions-interfaces/#union-type) that includes every entity defined in your subgraph's schema. - -You can query this field like so, providing a value for the `$representations` variable as shown: - -```graphql title="Query" -query ($representations: [_Any!]!) { - _entities(representations: $representations) { - ... on User { - id - username - } - } -} -``` - -```json title="Variable" -{ - "representations": [ - { - "__typename": "User", - "id": "5" - } - ] -} -``` - -#### Using in tests and debugging - -If you're writing integration tests for your subgraph, you can test the return value of the `_entities` field for various entity representations that your _other_ subgraphs use. - -If you're developing your subgraph in your local environment, you can [mock the return value](https://www.apollographql.com/docs/apollo-server/testing/mocking/) of the `_entities` field for your _other_ subgraphs so you don't have to connect those subgraphs to their respective data stores. - ## Custom directives in subgraphs The method for defining custom directives differs slightly for a federated graph, and it also depends on the version of Apollo Server you're using. @@ -382,4 +290,4 @@ const server = new ApolloServer({ }); ``` -Also make sure to read about the [gateway's support for custom directives](./gateway/#custom-directive-support). +Also make sure to read about the [gateway's support for custom directives](./router/#custom-directive-support). diff --git a/docs/source/building-supergraphs/subgraphs-overview.mdx b/docs/source/building-supergraphs/subgraphs-overview.mdx new file mode 100644 index 000000000..dfb5afc34 --- /dev/null +++ b/docs/source/building-supergraphs/subgraphs-overview.mdx @@ -0,0 +1,129 @@ +--- +title: Subgraphs +description: In a federated supergraph +--- + +Every federated supergraph includes one or more **subgraphs**. Each subgraph is a separate GraphQL service that's responsible for a different portion of your supergraph's available data. + +Here's a basic supergraph that includes two subgraphs (Users and Products): + +```mermaid +flowchart LR; + clients(Clients); + subgraph "Supergraph"; + gateway([Router]); + serviceA[Users
subgraph]; + serviceB[Products
subgraph]; + gateway --- serviceA & serviceB; + end; + clients -.- gateway; + class clients secondary; +``` + +You can implement different subgraphs using completely different programming languages and GraphQL server libraries! + +## Choosing a subgraph library + +Every subgraph in your supergraph should use a **subgraph-compatible GraphQL server library**. These are libraries that adhere to the Apollo Federation subgraph specification, which ensures that your supergraph can take full advantage of federation features like [entities](../entities/). + +[See federation-compatible subgraph libraries.](./supported-subgraphs/) + +After you select a subgraph library, consult its documentation to learn how to configure it to run as a subgraph. + +> If you're using Apollo Server as your subgraph library, see [Implementing a subgraph with Apollo Server](./subgraphs-apollo-server/). + +## Securing your subgraphs + +Implement any necessary firewall rules, access control lists, or other security measures in your environment to ensure that **only your supergraph's router** can access your individual subgraphs. + +**Clients should never query a subgraph directly!** Instead, clients should always query your router, which resolves those queries by communicating with your subgraphs. + +There are many reasons for this: + +- Subgraph libraries automatically add [powerful fields](#subgraph-specific-fields) to your schema that clients _should not_ have access to. + - The router uses these fields to cross subgraph boundaries while resolving complex operations. +- Providing a single endpoint for your entire supergraph reduces its overall [attack surface](https://en.wikipedia.org/wiki/Attack_surface). + +> In addition to the above security concerns, a significant benefit of _any_ GraphQL API is that clients only need to interact with one endpoint. This definitely holds true for a supergraph, especially one with tens or even hundreds of subgraphs! + +### Disabling CORS + +We recommend that subgraphs do not enable CORS (or at least, do not use the wildcard `access-control-allow-origin: *` header). This prevents attackers from exploiting a user's browser to access a subgraph directly. + +For Apollo Server subgraphs, you need to disable the default wildcard CORS policy (which is appropriate for many publicly-exposed servers but not for inaccessible servers like subgraphs). For details, see the [Apollo Server CORS documentation](/apollo-server/security/cors/#choosing-cors-options-for-your-project). + +## Subgraph-specific fields + +Subgraph-compatible server libraries automatically add some federation-specific definitions to your subgraph schema. In addition to directive definitions like `@key`, the most useful of these definitions for debugging are two fields of the `Query` type: `_service` and `_entities`: + +```graphql +type Query { + # ...your field definitions... + + # Added automatically + _service: _Service! + _entities(representations: [_Any!]!): [_Entity]! +} +``` + +### `Query._service` + +This field returns a `_Service` object with one field of its own: `sdl`. You can query it like so: + +```graphql +query GetSubgraphSchema { + _service { + sdl + } +} +``` + +The `sdl` field returns your subgraph's schema as an SDL string. This field has a couple of important differences from a standard [introspection query](https://graphql.org/learn/introspection/) that a tool like Apollo Sandbox uses: + +* Unlike introspection, the `sdl` field is _not_ disabled by default in production environments (this is safe if you properly [secure your subgraph](#securing-your-subgraphs)). +* Unlike introspection, the `sdl` field's returned string includes federation-specific directives like `@key`. + +### `Query._entities` + +> [Learn about entities](../entities/) if you haven't yet. + +This field takes a list of **entity representations** and returns a list of corresponding entities. + +> Whenever one subgraph references _another_ subgraph's entity, it uses an **entity representation** to do so. An entity representation is an object that includes _only_ the entity's `__typename` and the fields in the entity's `@key`. + +```graphql +_entities(representations: [_Any!]!): [_Entity]! +``` + +* The `_Any` type is a special scalar that enables you to provide entity representations of any valid shape. +* The `_Entity` type is a generated [union type](https://www.apollographql.com/docs/apollo-server/schema/unions-interfaces/#union-type) that includes every entity defined in your subgraph's schema. + +You can query this field like so, providing a value for the `$representations` variable as shown: + +```graphql title="Query" +query ($representations: [_Any!]!) { + _entities(representations: $representations) { + ... on User { + id + username + } + } +} +``` + +```json title="Variable" +{ + "representations": [ + { + "__typename": "User", + "id": "5" + } + ] +} +``` + +#### Using in tests and debugging + +If you're writing integration tests for your subgraph, you can test the return value of the `_entities` field for various entity representations that your _other_ subgraphs use. + +If you're developing your subgraph in your local environment, you can [mock the return value](https://www.apollographql.com/docs/apollo-server/testing/mocking/) of the `_entities` field for your _other_ subgraphs so you don't have to connect those subgraphs to their respective data stores. diff --git a/docs/source/supported-subgraphs.md b/docs/source/building-supergraphs/supported-subgraphs.md similarity index 100% rename from docs/source/supported-subgraphs.md rename to docs/source/building-supergraphs/supported-subgraphs.md diff --git a/docs/source/config.json b/docs/source/config.json index 04f08f7b8..5c69efce5 100644 --- a/docs/source/config.json +++ b/docs/source/config.json @@ -26,9 +26,10 @@ "4️⃣ Working with subgraphs": "/quickstart/local-subgraphs" }, "Building Your Supergraph": { - "Subgraphs in Apollo Server": "/subgraphs", - "Other subgraph libraries": "/supported-subgraphs", - "The graph router/gateway": "/router" + "Subgraphs": "/building-supergraphs/subgraphs-overview", + "Supported subgraph libraries": "/building-supergraphs/supported-subgraphs", + "Router/gateway": "/building-supergraphs/router", + "Apollo Server subgraphs": "/building-supergraphs/subgraphs-apollo-server" }, "Federated Schemas": { "Overview": "/federated-types/overview", diff --git a/docs/source/entities-advanced.mdx b/docs/source/entities-advanced.mdx index fd8dfdc8f..8d29d4afb 100644 --- a/docs/source/entities-advanced.mdx +++ b/docs/source/entities-advanced.mdx @@ -272,7 +272,7 @@ We're done! `Bill` now originates in a new subgraph, and it was resolvable durin -> ⚠️ We strongly recommend _against_ using `IntrospectAndCompose` in production. For details, see [Limitations of `IntrospectAndCompose`](./gateway/#limitations-of-introspectandcompose). +> ⚠️ We strongly recommend _against_ using `IntrospectAndCompose` in production. For details, see [Limitations of `IntrospectAndCompose`](./building-supergraphs/router/#limitations-of-introspectandcompose). When you provide `IntrospectAndCompose` to `ApolloGateway`, it performs composition _itself_ on startup after fetching all of your subgraph schemas. If this runtime composition fails, the gateway fails to start up, resulting in downtime. diff --git a/docs/source/entities.mdx b/docs/source/entities.mdx index a9a85ed6e..91d5eb840 100644 --- a/docs/source/entities.mdx +++ b/docs/source/entities.mdx @@ -68,7 +68,7 @@ The `@key` directive defines the entity's **primary key**, which consists of one The `@key` directive effectively tells the router, "This subgraph can resolve an instance of this entity if you provide its primary key." In order for this to be true, the subgraph needs to define a **reference resolver** for the entity. -> ⚠️ **This section describes how to create reference resolvers in Apollo Server.** If you're using another [subgraph-compatible library](./supported-subgraphs/), see its documentation for creating reference resolvers. +> ⚠️ **This section describes how to create reference resolvers in Apollo Server.** If you're using another [subgraph-compatible library](./building-supergraphs/supported-subgraphs/), see its documentation for creating reference resolvers. For the `Product` entity defined [above](#1-define-a-key), the reference resolver might look like this: diff --git a/docs/source/errors.md b/docs/source/errors.md index 811ea3bc6..4630c3b9c 100644 --- a/docs/source/errors.md +++ b/docs/source/errors.md @@ -3,7 +3,7 @@ title: Federation error codes sidebar_title: Error codes --- -When Apollo Gateway attempts to **compose** the schemas provided by your [subgraphs](./subgraphs/) into a **supergraph schema**, it confirms that: +When Apollo Gateway attempts to **compose** the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a **supergraph schema**, it confirms that: * The subgraphs are valid * The resulting supergraph schema is valid diff --git a/docs/source/federated-types/federated-directives.mdx b/docs/source/federated-types/federated-directives.mdx index eed51615f..3e806f661 100644 --- a/docs/source/federated-types/federated-directives.mdx +++ b/docs/source/federated-types/federated-directives.mdx @@ -108,7 +108,7 @@ type Product @key(fields: "upc") @key(fields: "sku") { } ``` -To check whether your subgraph library supports repeatable directives, see the `repeatable @key` item in [Federation-compatible subgraph implementations](../supported-subgraphs/). +To check whether your subgraph library supports repeatable directives, see the `repeatable @key` item in [Federation-compatible subgraph implementations](../building-supergraphs/supported-subgraphs/). > ⚠️ **Do not apply `@key` to interface definitions.** The `INTERFACE` location is included in this definition for backward compatibility with Federation 1 subgraphs. Currently, applying `@key` to an interface has no effect in _any_ version of federation, and Federation 2 subgraphs produce a composition error to emphasize this. diff --git a/docs/source/federated-types/sharing-types.mdx b/docs/source/federated-types/sharing-types.mdx index 98df328aa..b1520bb96 100644 --- a/docs/source/federated-types/sharing-types.mdx +++ b/docs/source/federated-types/sharing-types.mdx @@ -7,7 +7,7 @@ description: Share types and fields across multiple subgraphs > >For more information about using value types in Federation 1, you can view the [previous version of this article](/federation/v1/value-types/). -In a federated graph, it's common to want to reuse a GraphQL type across multiple [subgraphs](../subgraphs/). +In a federated graph, it's common to want to reuse a GraphQL type across multiple [subgraphs](../building-supergraphs/subgraphs-overview/). For example, suppose you want to define and reuse a generic `Position` type in different subgraphs: diff --git a/docs/source/federation-2/moving-to-federation-2.mdx b/docs/source/federation-2/moving-to-federation-2.mdx index 87b03f58d..a76d01bf5 100644 --- a/docs/source/federation-2/moving-to-federation-2.mdx +++ b/docs/source/federation-2/moving-to-federation-2.mdx @@ -147,7 +147,7 @@ To use new Federation 2 features and their associated directives, it's helpful t npm install @apollo/subgraph ``` -* If your subgraph uses another server library, check the [compatibility table](../supported-subgraphs/) to see whether it supports Federation 2 directives yet. If it does, consult that library's documentation to determine which version you need to update to. +* If your subgraph uses another server library, check the [compatibility table](../building-supergraphs/supported-subgraphs/) to see whether it supports Federation 2 directives yet. If it does, consult that library's documentation to determine which version you need to update to. * If your library _doesn't_ support Federation 2 directives yet, you can still use that library with Federation 2 if the library lets you add custom directive definitions to your schema! ### Opt in to Federation 2 @@ -168,7 +168,7 @@ This definition identifies a schema as a Federation 2 schema, and it `import`s a ### Add directive definitions if needed -Currently, not all [subgraph libraries](../supported-subgraphs/) provide built-in support for Federation 2 directives (such as `@shareable`). If your library doesn't provide this support, you need to add the following directive definitions to your subgraph schema: +Currently, not all [subgraph libraries](../building-supergraphs/supported-subgraphs/) provide built-in support for Federation 2 directives (such as `@shareable`). If your library doesn't provide this support, you need to add the following directive definitions to your subgraph schema: diff --git a/docs/source/federation-2/new-in-federation-2.mdx b/docs/source/federation-2/new-in-federation-2.mdx index 136620448..290e51d4d 100644 --- a/docs/source/federation-2/new-in-federation-2.mdx +++ b/docs/source/federation-2/new-in-federation-2.mdx @@ -16,7 +16,7 @@ Before covering what's new, here's what _isn't_ changing in Federation 2: * Graphs that _do_ require changes are graphs that _should_ cause composition errors, but Federation 1 fails to detect them. [Learn more.](./backward-compatibility/#do-i-need-to-modify-my-subgraph-schemas-to-use-federation-2) * To take full advantage of Federation 2 features, you do need to make some changes to your subgraph schemas, but you can make these changes incrementally at your convenience. See [Moving to Apollo Federation 2](./moving-to-federation-2/). -* Subgraph servers have no additional requirements. Any [subgraph-compatible library](../supported-subgraphs/) is automatically compatible with Federation 2. +* Subgraph servers have no additional requirements. Any [subgraph-compatible library](../building-supergraphs/supported-subgraphs/) is automatically compatible with Federation 2. * Many subgraph-compatible libraries do not yet automatically define certain directives that are new in Federation 2, such as `@shareable`. You can [define these directives manually](./moving-to-federation-2/#add-directive-definitions-if-needed) to use them in your subgraph schemas. ## More flexible composition diff --git a/docs/source/hints.md b/docs/source/hints.md index 92752f651..c8b7b291b 100644 --- a/docs/source/hints.md +++ b/docs/source/hints.md @@ -2,7 +2,7 @@ title: Composition hints --- -When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./subgraphs/) into a supergraph schema, the composition process might output **hints** that provide additional information about the result. Hints are primarily informative and _do not_ necessarily indicate that a problem needs to be fixed. +When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process might output **hints** that provide additional information about the result. Hints are primarily informative and _do not_ necessarily indicate that a problem needs to be fixed. Hints are categorized under the following levels: diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 8cc3b6b9b..6ecaebf54 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -125,10 +125,12 @@ graph BT; class clients secondary; ``` -* The router is one of the following: - * [The Apollo Router](https://www.apollographql.com/docs/router/) (recommended): a high-performance, precompiled Rust executable - * An instance of Apollo Server using special extensions from the [`@apollo/gateway`](./api/apollo-gateway) library -* 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](./supported-subgraphs/). Different subgraphs in the same supergraph can even use different server libraries. +- The router is one of the following: + - [The Apollo Router](https://www.apollographql.com/docs/router/) (recommended): a high-performance, precompiled Rust executable + - An instance of Apollo Server using special extensions from the [`@apollo/gateway`](./api/apollo-gateway) library +- Subgraphs can each run any [subgraph-compatible GraphQL server](./building-supergraphs/supported-subgraphs/). + - This includes Apollo Server using special extensions from the [`@apollo/subgraph`](./api/apollo-subgraph) library. + - Different subgraphs in the same supergraph can even use different server libraries. ## Benefits of federation diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index 8e8e786d3..fa7e2a1a5 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -3,13 +3,13 @@ title: Deploying with managed federation description: Best practices --- -When rolling out changes to a [subgraph](../subgraphs/), we recommend the following workflow: +When rolling out changes to a [subgraph](../building-supergraphs/subgraphs-overview/), we recommend the following workflow: -1. Confirm the backward compatibility of each change by [running `rover subgraph check`](https://www.apollographql.com/docs/rover/subgraphs/#checking-subgraph-schema-changes) in your CI pipeline. +1. Confirm the backward compatibility of each change by [running `rover subgraph check`](/rover/subgraphs/#checking-subgraph-schema-changes) in your CI pipeline. 2. Merge backward compatible changes that successfully pass schema checks. 3. Deploy changes to the subgraph in your infrastructure. 4. Wait until all replicas finish deploying. -5. Run [`rover subgraph publish`](https://www.apollographql.com/docs/rover/subgraphs/#publishing-a-subgraph-schema-to-apollo-studio) to update your managed federation configuration: +5. Run [`rover subgraph publish`](/rover/subgraphs/#publishing-a-subgraph-schema-to-apollo-studio) to update your managed federation configuration: ```bash rover subgraph publish my-supergraph@my-variant \ @@ -20,7 +20,7 @@ rover subgraph publish my-supergraph@my-variant \ ## Pushing configuration updates safely -Whenever possible, you should update your subgraph configuration in a way that is backward compatible to avoid downtime. As suggested above, the best way to do this is to run `rover subgraph check` before updating. You should also generally seek to minimize the number of [breaking changes](https://www.apollographql.com/docs/studio/schema-checks/#potentially-breaking-changes) you make to your schemas. +Whenever possible, you should update your subgraph configuration in a way that is backward compatible to avoid downtime. As suggested above, the best way to do this is to run `rover subgraph check` before updating. You should also generally seek to minimize the number of [breaking changes](/studio/schema-checks/#potentially-breaking-changes) you make to your schemas. Additionally, **call `rover subgraph publish` for a subgraph only after all replicas of that subgraph are deployed**. This ensures that resolvers are in place for all operations that are executable against your graph, and operations can't attempt to access fields that do not yet exist. @@ -143,7 +143,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 you [associate metrics with variants](https://www.apollographql.com/docs/studio/schema/registry/#associating-metrics-with-a-variant) as well, you can use [Apollo Studio](https://studio.apollographql.com) 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 you [associate metrics with variants](/studio/schema/registry/#associating-metrics-with-a-variant) as well, you can use [Apollo Studio](https://studio.apollographql.com) 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 diff --git a/docs/source/metrics.md b/docs/source/metrics.md index 2f82f6ff7..4fceb13fb 100644 --- a/docs/source/metrics.md +++ b/docs/source/metrics.md @@ -9,7 +9,7 @@ Apollo Federation supports sending **federated traces** from your graph router, 1. The router receives an operation from a client. 2. The router constructs a query plan for the operation, delegating sub-queries to subgraphs. -3. For each [fetch](./subgraph-spec/#fetch-service-capabilities) to a subgraph, a response is received. +3. For each fetch to a subgraph, a response is received. 4. The [`extensions`](/resources/graphql-glossary/#extensions) of each response includes a trace from the sub-query. 5. The router collects the set of sub-query traces from subgraphs and arranges them in the shape of the query plan. 6. The federated trace is sent to the Apollo [metrics ingress](/studio/metrics/usage-reporting/) for processing. diff --git a/docs/source/migrating-from-stitching.md b/docs/source/migrating-from-stitching.md index 6fa00ecf4..4dd508f4d 100644 --- a/docs/source/migrating-from-stitching.md +++ b/docs/source/migrating-from-stitching.md @@ -59,7 +59,7 @@ const server = new ApolloServer({ ### Using a GraphQL server besides Apollo Server -There are [several community-contributed packages](./supported-subgraphs/) that add federation support to other GraphQL runtimes. +There are [several community-contributed packages](./building-supergraphs/supported-subgraphs/) that add federation support to other GraphQL runtimes. ## Step 2: Register your schemas with a GraphQL registry @@ -177,7 +177,7 @@ After you've fully migrated your graph and incoming traffic to use your federate You can now begin to modify your existing schema to take full advantage of the features that federation provides. These features include: -* Greater flexibility with [federation core concepts](./subgraphs/) +* Greater flexibility with [federation core concepts](./) * [Metrics and analysis of query plans](./performance/monitoring/#metrics-and-observability) * [Gateway support for live schema updates](./managed-federation/deployment/#the-subgraph-publish-lifecycle) * [Validation of composition logic and usage traffic](./managed-federation/federated-schema-checks/) diff --git a/docs/source/query-plans.mdx b/docs/source/query-plans.mdx index 12372f7d5..dd82fe91f 100644 --- a/docs/source/query-plans.mdx +++ b/docs/source/query-plans.mdx @@ -434,7 +434,7 @@ Instead of containing a GraphQL operation, this `Fetch` node contains two **Grap * The first fragment is a **representation** of the entity being resolved (in this case, `Hotel`). [Learn more about entity representations](./entities/#2-define-a-reference-resolver). * The second fragment contains the entity fields and subfields that the router needs the subgraph to resolve (in this case, `Hotel.reviews` and `Review.rating`). -When the router sees this special `Fetch` syntax, it knows to query a subgraph's [`Query._entities` field](./subgraphs/#query_entities). This field is what enables a subgraph to provide direct access to any available fields of an entity. +When the router sees this special `Fetch` syntax, it knows to query a subgraph's [`Query._entities` field](./building-supergraphs/subgraphs-overview/#query_entities). This field is what enables a subgraph to provide direct access to any available fields of an entity. Now that you've learned about each query plan node, take another look at the example query plan in [Example graph](#example-graph) to see how these nodes work together in a complete query plan. diff --git a/docs/source/quickstart/local-subgraphs.mdx b/docs/source/quickstart/local-subgraphs.mdx index d34456c63..751c3fc86 100644 --- a/docs/source/quickstart/local-subgraphs.mdx +++ b/docs/source/quickstart/local-subgraphs.mdx @@ -5,7 +5,7 @@ description: Part 4 - Working with subgraphs In the previous parts of this quickstart, we used Apollo-hosted services for our subgraphs. Now, let's see what we can do with our _own_ subgraphs. -Our subgraphs can use any GraphQL server library that supports Apollo Federation. This includes Apollo Server, along with the other libraries listed in [Federation-compatible subgraph implementations](../supported-subgraphs/). +Our subgraphs can use any GraphQL server library that supports Apollo Federation. This includes Apollo Server, along with the other libraries listed in [Federation-compatible subgraph implementations](../building-supergraphs/supported-subgraphs/). ## 1. Configure Apollo Server diff --git a/docs/source/quickstart/setup.mdx b/docs/source/quickstart/setup.mdx index edad75130..c66ba118c 100644 --- a/docs/source/quickstart/setup.mdx +++ b/docs/source/quickstart/setup.mdx @@ -186,7 +186,7 @@ As mentioned in [Federation concepts](#federation-concepts), your federated supe > **The Apollo Router** is a high-performance, precompiled Rust executable that acts as the router for a supergraph. > -> Alternatively, _Apollo Server_ can act as your graph router, as documented in [The graph router](../gateway/). This tutorial uses the Apollo Router because it's the recommended default for all new supergraphs (for details, see [Choosing a router library](../gateway/#choosing-a-router-library)). +> Alternatively, _Apollo Server_ can act as your graph router, as documented in [The graph router](../building-supergraphs/router/). This tutorial uses the Apollo Router because it's the recommended default for all new supergraphs (for details, see [Choosing a router library](../building-supergraphs/router/#choosing-a-router-library)). On your development machine, first create a new directory for your router project. Then inside that directory, run the following to install the Apollo Router: diff --git a/docs/source/subgraph-spec.mdx b/docs/source/subgraph-spec.mdx index ac1fdafc4..37ac9ad7b 100644 --- a/docs/source/subgraph-spec.mdx +++ b/docs/source/subgraph-spec.mdx @@ -3,7 +3,7 @@ title: Apollo Federation subgraph specification description: For adding subgraph support to GraphQL server libraries --- -> This content is provided for developers adding federated subgraph support to a GraphQL server library, and for anyone curious about the inner workings of federation. You do _not_ need to read this if you're building a supergraph with existing [subgraph-compatible libraries](./supported-subgraphs/), such as Apollo Server. +> This content is provided for developers adding federated subgraph support to a GraphQL server library, and for anyone curious about the inner workings of federation. You do _not_ need to read this if you're building a supergraph with existing [subgraph-compatible libraries](./building-supergraphs/supported-subgraphs/), such as Apollo Server. > > Servers that are partially or fully compatible with this specification are tracked in Apollo's [subgraph compatibility repository](https://github.com/apollographql/apollo-federation-subgraph-compatibility). diff --git a/internals-js/src/genErrorCodeDoc.ts b/internals-js/src/genErrorCodeDoc.ts index c35c23b39..408ba2fbc 100644 --- a/internals-js/src/genErrorCodeDoc.ts +++ b/internals-js/src/genErrorCodeDoc.ts @@ -6,7 +6,7 @@ title: Federation error codes sidebar_title: Error codes --- -When Apollo Gateway attempts to **compose** the schemas provided by your [subgraphs](./subgraphs/) into a **supergraph schema**, it confirms that: +When Apollo Gateway attempts to **compose** the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a **supergraph schema**, it confirms that: * The subgraphs are valid * The resulting supergraph schema is valid