From 10737e223b39a8b1204cd273e8bbed44c31a2e70 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Thu, 30 May 2024 11:43:26 -0700 Subject: [PATCH 1/2] docs: context directives (#2975) Docs for `@context` and `@fromContext` directives. --------- Co-authored-by: Maria Elisabeth Schreiber --- docs/source/entities-advanced.mdx | 184 ++++++++++++++++++ .../federated-types/federated-directives.mdx | 63 ++++++ docs/source/federation-versions.mdx | 86 +++++++- 3 files changed, 332 insertions(+), 1 deletion(-) diff --git a/docs/source/entities-advanced.mdx b/docs/source/entities-advanced.mdx index d68016ad3..0069d9ed2 100644 --- a/docs/source/entities-advanced.mdx +++ b/docs/source/entities-advanced.mdx @@ -909,3 +909,187 @@ const resolvers = { A basic implementation of the `fetchProductByID` function might make a database call each time it's called. If we need to resolve `Product.price` for `N` different products, this results in `N` database calls. These calls are made in addition to the call made by the Reviews subgraph to fetch the initial list of reviews (and the `id` of each product). This is where the "N+1" problem gets its name. If not prevented, this problem can cause performance problems or even enable denial-of-service attacks. This problem is not limited to reference resolvers. In fact, it can occur with any resolver that fetches from a data store. To handle this problem, we strongly recommend using [the dataloader pattern](https://github.com/graphql/dataloader). Nearly every GraphQL server library provides a dataloader implementation, and you should use it in every resolver. This is true even for resolvers that aren't for entities and that don't return a list. These resolvers can still cause N+1 issues via [batched requests](/technotes/TN0021-graph-security/#batched-requests). + + + +## Using contexts to share data along type hierarchies + + + +Use the `@context` and `@fromContext` directives to set and get a _context_ to share data between types in a subgraph. Contexts provide a way for a subgraph to share data between types of a nested-type hierarchy without overloading entity keys with extraneous fields. Contexts also preserve the separation of concerns between different subgraphs. + +In an entity, a nested object may have a dependency on an ancestor type and thus need access to that ancestor's field(s). + +To enable a descendant to access an ancestor's field, you could add it as a `@key` field to every entity along the chain of nested types, but that can become problematic. Deeply nested types can change the `@key` fields of many entities. The added field may be irrelevant to the entities it's added to. Most importantly, overloading `@key` fields often breaks the separation of concerns between different subgraphs. + +The `@context` and `@fromContext` directives enable a subgraph to share fields without overloading `@key` fields. You can use these directives to define one or more contexts in a subgraph. + +### Using one context + +As an example of a single context, the subgraph below tracks the last financial transaction made per user. The `Transaction` type is a child of the `User` type. Each transaction depends on the associated user's currency to calculate the transaction amount in the user's currency. That dependency—the `currencyCode` argument of a `Transaction` depending on the `userCurrency { isoCode } ` of a `User`— is defined with a context. The `@context` directive on `User` sets the context, and `@fromContext` on `currencyCode` gets the contextual data. + +```graphql title="Example: using @context and @fromContext" +scalar CurrencyCode; + +type Currency { + id: ID! + isoCode: CurrencyCode! +} + +type User @key(fields: "id") @context(name: "userContext") { + id: ID! + lastTransaction: Transaction! + userCurrency: Currency! +} + +type Transaction @key(fields: "id") { + id: ID! + currency: Currency! + amount: Int! + amountInUserCurrency( + currencyCode: CurrencyCode + @fromContext(field: "$userContext { userCurrency { isoCode } }") + ): Int! +} +``` + + + +An argument of `@fromContext` doesn't appear in the API schema. Instead, it's populated automatically by the router. + +In the example above, the argument `currencyCode: CurrencyCode!` wouldn't appear in the API schema. + + + +### Using multiple contexts + +As an example using multiple contexts, the subgraph below has three entities using two contexts and a nested child entity referencing fields using those contexts: + +```graphql title="Example: using multiple contexts" +type Query { + a: A! + b: B! + c: C! +} + +type A @key(fields: "id") @context(name: "context_1") @context(name: "context_2") { + id: ID! + field: String! + child: Child! +} + +type B @key(fields: "id") @context(name: "context_1") @context(name: "context_2") { + id: ID! + field: String! + child: Child! +} + +type C @key(fields: "id") @context(name: "context_1") { + id: ID! + anotherField: String! + child: Child! +} + +type Child @key(fields: "id") { + id: ID! + prop1( + arg: String! @fromContext(field: "$context_1 { field }") + ): Int! + prop2( + arg: String! + @fromContext(field: "$context_2 ... A { field } ... B { field } ... C { anotherField }") + ): Int! +} +``` + +When the same contextual value is set in multiple places—as in the example with the `Child.prop1` and `Child.prop2` `args`—the `FieldValue` must resolve all types from each place into a single value that matches the parameter type. + + + +Federation doesn't guarantee which context will be used if a field is reachable via multiple contexts. + + + +### Disambiguating contexts + +When multiple ancestor entities in the type hierarchy could fulfill a set context, the nearest ancestor is chosen. For example, if both the parent and grandparent of a type can provide the value of a context, the parent is chosen because it's the closer ancestor. + +In the following example, given nested types `A`, `B`, and `C`, with `C` referencing a context that either `A` or `B` could provide, `C` uses the value from `B` because it's a closer ancestor to `C` than `A`: + +```graphql +type Query { + a: A! +} + +type A @key(fields: "id") @context(name: "context_1") { + id: ID! + field: String! + b: B! +} + +type B @key(fields: "id") @context(name: "context_1") { + id: ID! + field: String! + c: C! +} + +type C @key(fields: "id") { + id: ID! + prop( + arg: String! @fromContext(field: "$context_1 { field }") + ): Int! +} +``` + +In a more complex graph, a field could be reachable via multiple paths, and a different field could be used to resolve the `prop` depending on which path was used. + +### Referencing fields across subgraphs + +The definition of context scopes can only exist in one subgraph schema. The `@fromContext` directive can't reference a `@context` defined in another subgraph. However, you can use contexts to share data across subgraphs using the `@external` reference. + +Reusing the [`Transaction` example](#using-one-context), imagine a subgraph responsible for the `User` and `Currency` types: + +```graphql +scalar CurrencyCode + +type Currency @shareable { + id: ID! + isoCode: CurrencyCode! +} + +type User @key(fields: "id") { + id: ID! + userCurrency: Currency! +} +``` + +If you want to reference those fields from another subgraph, you can use the `@external` directive to pass data across subgraph boundaries: + +```graphql +scalar CurrencyCode + +type Currency @shareable { + id: ID! + isoCode: CurrencyCode! +} + +type User @key(fields: "id") @context(name: "userContext") { + id: ID! + + # This is a reference to the field resolved elsewhere + userCurrency: Currency! @external + + # We add this field to our type here + lastTransaction: Transaction! +} + +type Transaction @key(fields: "id") { + id: ID! + currency: Currency! + amount: Int! + amountInUserCurrency( + currencyCode: CurrencyCode + @fromContext(field: "$userContext { userCurrency { isoCode } }") + ): Int! +} +``` diff --git a/docs/source/federated-types/federated-directives.mdx b/docs/source/federated-types/federated-directives.mdx index fdd326396..c265649c3 100644 --- a/docs/source/federated-types/federated-directives.mdx +++ b/docs/source/federated-types/federated-directives.mdx @@ -913,3 +913,66 @@ If different subgraphs use different versions of a directive's corresponding spe + +## Saving and referencing data with contexts + + + +### `@context` + + + +The `@context` directive defines a named context from which a field of the annotated type can be passed to a receiver of the context. The receiver must be a field annotated with the `@fromContext` directive. + +```graphql +directive @context(name: String!) on OBJECT | INTERFACE | UNION; +``` + +A `@context` directive must be applied to an object, interface, or union type. A type can be annotated with one or more `@context` directives. + +Each `@context` must be defined with a name, and each `@context` name can be applied to multiple places within a subgraph. For example: + +```graphql +type A @key(fields: "id") @context(name: "userContext") { + id: ID! + prop: String! +} + +type B @key(fields: "id") @context(name: "userContext") { + id: ID! + prop: String! +} + +type U @key(fields: "id") { + id: ID! + field (arg: String @fromContext(field: "$userContext { prop }")): String! +} +``` + + + +### `@fromContext` + + + +The `@fromContext` directive sets the context from which to receive the value of the annotated field. The context must have been defined with the `@context` directive. + +```graphql +scalar FieldValue; + +directive @fromContext(field: FieldValue!) on ARGUMENT_DEFINITION; +``` + +A `@fromContext` directive must be used as an argument on a field. Its field value—the `FieldValue` scalar—must contain the name of a defined context and a selection of a field from the context's type. + +The selection syntax for `@fromContext` used in its `FieldValue` is similar to GraphQL field selection syntax, with some additional rules: +- The first element must be the name of a context defined by `@context` and prefixed with `$` (for example, `$myContext`). This is the only context that can be referenced by the annotated field. +- The `@skip` and `@include` directives must not be used. +- The second element must be a selection set that resolves to a single field. +- Top-level type conditions must not overlap with one another, so that the field can be resolved to a single value. +- All fields referenced in the `FieldValue` must be expressed within the current subgraph. If the fields are referenced across multiple subgraphs, they must be annotated with [`@external`](../entities-advanced/#referencing-fields-across-subgraphs) . +- The argument must be nullable. Because validation is done at the subgraph level, the referenced field may become nullable when merging subgraphs, such as when the field is nullable in one subgraph but not in another. + +When the same contextual value is set in multiple places, the `FieldValue` must resolve all types from each place into a single value that matches the parameter type. + +For examples using `@context` and `@fromContext`, see [Using contexts to share data along type hierarchies](../entities-advanced/#using-contexts-to-share-data-along-type-hierarchies). diff --git a/docs/source/federation-versions.mdx b/docs/source/federation-versions.mdx index 5463324ee..ae44c5afc 100644 --- a/docs/source/federation-versions.mdx +++ b/docs/source/federation-versions.mdx @@ -25,6 +25,90 @@ For a comprehensive changelog for Apollo Federation and its associated libraries - If you maintain a [subgraph-compatible library](./building-supergraphs/supported-subgraphs/), consult this article to stay current with recently added directives. All of these directive definitions are also listed in the [subgraph specification](./subgraph-spec/#subgraph-schema-additions). +## v2.8 + +
+ + + +
+ +First release + +**May 2024** + +
+ +
+ +Available in GraphOS? + +**No** + +
+ +
+ +Minimum router version + +**1.48.0** + +
+ + + +
+ +#### Directive changes + + + + + + + + + + + + + + + + + + + + + +
TopicDescription
+ +##### `@context` + + + +Introduced. [Learn more](./federated-types/federated-directives/#context). + +```graphql +directive @context(name: String!) on OBJECT | INTERFACE | UNION; +``` + +
+ +##### `@fromContext` + + + +Introduced. [Learn more](./federated-types/federated-directives/#fromcontext). + +```graphql +scalar FieldValue; + +directive @fromContext(field: FieldValue!) on ARGUMENT_DEFINITION; +``` + +
+ ## v2.7
@@ -35,7 +119,7 @@ For a comprehensive changelog for Apollo Federation and its associated libraries First release -February 2024 +**February 2024** From 19746ad1d60904d330ca5dd327da4adffa3fafeb Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Thu, 30 May 2024 15:48:56 -0400 Subject: [PATCH 2/2] docs: update frontmatter (#2992) Updates subtitles and meta descriptions for better discoverability. --- .../jetbrains-ide-support.mdx | 4 +- docs/source/building-supergraphs/router.mdx | 7 +-- .../subgraphs-overview.mdx | 5 +- .../supported-subgraphs.md | 5 +- docs/source/config.json | 46 +++++++++---------- docs/source/entities-advanced.mdx | 4 +- docs/source/entities.mdx | 3 +- docs/source/errors.mdx | 5 +- docs/source/federated-types/composition.mdx | 5 +- .../federated-types/federated-directives.mdx | 4 +- docs/source/federated-types/interfaces.mdx | 5 +- docs/source/federated-types/overview.mdx | 5 +- docs/source/federated-types/sharing-types.mdx | 5 +- .../federation-2/backward-compatibility.mdx | 5 +- .../federation-2/moving-to-federation-2.mdx | 3 +- .../federation-2/new-in-federation-2.mdx | 4 +- docs/source/federation-versions.mdx | 5 +- docs/source/hints.mdx | 4 +- docs/source/index.mdx | 2 +- docs/source/managed-federation/deployment.mdx | 4 +- .../managed-federation/error-reporting.mdx | 4 +- .../federated-schema-checks.mdx | 4 +- docs/source/managed-federation/overview.mdx | 4 +- docs/source/managed-federation/setup.mdx | 4 +- docs/source/managed-federation/uplink.mdx | 3 +- docs/source/metrics.md | 5 +- docs/source/migrating-from-stitching.md | 5 +- docs/source/opentelemetry.mdx | 2 + docs/source/performance/caching.mdx | 4 +- docs/source/performance/monitoring.mdx | 4 +- docs/source/query-plans.mdx | 5 +- docs/source/quickstart/local-composition.mdx | 5 +- docs/source/quickstart/local-subgraphs.mdx | 7 +-- docs/source/quickstart/setup.mdx | 5 +- docs/source/quickstart/studio-composition.mdx | 5 +- docs/source/subgraph-spec.mdx | 5 +- 36 files changed, 122 insertions(+), 79 deletions(-) diff --git a/docs/source/building-supergraphs/jetbrains-ide-support.mdx b/docs/source/building-supergraphs/jetbrains-ide-support.mdx index b5a5fa126..f6c306c18 100644 --- a/docs/source/building-supergraphs/jetbrains-ide-support.mdx +++ b/docs/source/building-supergraphs/jetbrains-ide-support.mdx @@ -1,5 +1,7 @@ --- -title: Federation support in JetBrains IDEs +title: Federation Support in JetBrains IDEs +subtitle: Streamline federated GraphQL development +description: Enhance your development workflow with federation-specific features in IntelliJ-based IDEs using the GraphQL Plugin. --- The [GraphQL Plugin for JetBrains](https://plugins.jetbrains.com/plugin/8097-graphql/) provides federation-specific development features, such as auto-complete for federation directives. However, you must enable this federation support after installing the plugin. Otherwise, your IDE might display unexpected errors while you're working with a subgraph schema. diff --git a/docs/source/building-supergraphs/router.mdx b/docs/source/building-supergraphs/router.mdx index 05e0063cf..e194536b3 100644 --- a/docs/source/building-supergraphs/router.mdx +++ b/docs/source/building-supergraphs/router.mdx @@ -1,6 +1,7 @@ --- -title: The router -description: The entry point to your supergraph +title: The Router +subtitle: Learn about the entry point to your federated GraphQL API +description: Learn how to configure a router to act as the gateway to your subgraphs, facilitating seamless execution of operations across multiple services. Efficiently manage and orchestrate your federated supergraph with a robust router setup. --- After you set up at least one federation-ready [subgraph](./subgraphs-overview/), you can configure a router 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: @@ -25,7 +26,7 @@ Apollo actively supports the following options for your router: - **The Apollo Router (recommended)**: This is a high-performance, precompiled Rust binary. - 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. - - You can also host your own Apollo Router instances. [See the federation quickstart](../quickstart/setup/) to get started. + - You can also host your own Apollo Router instances. [See the Federation Quickstart](../quickstart/setup/) to get started. - **Apollo Server**: Apollo Server can act as your router via the [`@apollo/gateway`](https://www.npmjs.com/package/@apollo/gateway) extension library. - [See how to set up Apollo Gateway](/apollo-server/using-federation/apollo-gateway-setup). diff --git a/docs/source/building-supergraphs/subgraphs-overview.mdx b/docs/source/building-supergraphs/subgraphs-overview.mdx index 244277cda..8f017f195 100644 --- a/docs/source/building-supergraphs/subgraphs-overview.mdx +++ b/docs/source/building-supergraphs/subgraphs-overview.mdx @@ -1,6 +1,7 @@ --- title: Subgraphs -description: In a federated supergraph +subtitle: Learn about subgraphs in a federated supergraph +description: Understand the concept of subgraphs, explore library options, and learn how to secure and optimize your subgraphs for efficient supergraph operations. --- 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. @@ -20,7 +21,7 @@ flowchart LR; class clients secondary; ``` -You can implement different subgraphs using completely different programming languages and GraphQL server libraries! +You can implement different subgraphs using completely different programming languages and GraphQL server libraries. ## Choosing a subgraph library diff --git a/docs/source/building-supergraphs/supported-subgraphs.md b/docs/source/building-supergraphs/supported-subgraphs.md index 5e3895586..471bd3e9b 100644 --- a/docs/source/building-supergraphs/supported-subgraphs.md +++ b/docs/source/building-supergraphs/supported-subgraphs.md @@ -1,6 +1,7 @@ --- -title: Federation-compatible subgraph implementations -description: For use in a federated supergraph +title: Federation-Compatible Subgraph Implementations +subtitle: Reference for compatible GraphQL server libraries +description: Reference for open-source GraphQL server libraries and hosted solutions that are compatible with Apollo Federation. --- The following open-source GraphQL server libraries and hosted solutions support acting as a subgraph in a federated supergraph. 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. diff --git a/docs/source/config.json b/docs/source/config.json index b478af960..a01ae7c76 100644 --- a/docs/source/config.json +++ b/docs/source/config.json @@ -14,57 +14,57 @@ "Introduction": "/", "Changelog": "/federation-versions", "Quickstart": { - "Project setup": "/quickstart/setup", + "Project Setup": "/quickstart/setup", "Composition in GraphOS Studio": "/quickstart/studio-composition", - "Local composition": "/quickstart/local-composition", - "Working with subgraphs": "/quickstart/local-subgraphs" + "Local Composition": "/quickstart/local-composition", + "Working with Subgraphs": "/quickstart/local-subgraphs" }, "Building Your Supergraph": { "Subgraphs": "/building-supergraphs/subgraphs-overview", - "Supported subgraph libraries": "/building-supergraphs/supported-subgraphs", - "Router / Gateway": "/building-supergraphs/router", - "Apollo Server subgraphs": "https://apollographql.com/docs/apollo-server/using-federation/apollo-subgraph-setup", + "Supported Subgraph Libraries": "/building-supergraphs/supported-subgraphs", + "Router": "/building-supergraphs/router", + "Apollo Server Subgraphs": "https://apollographql.com/docs/apollo-server/using-federation/apollo-subgraph-setup", "JetBrains IDE Support": "/building-supergraphs/jetbrains-ide-support" }, "Federated Schemas": { "Overview": "/federated-types/overview", "Composition": "/federated-types/composition", - "Federated directives": "/federated-types/federated-directives", - "Sharing types (value types)": "/federated-types/sharing-types", - "Introduction to entities": "/entities", - "Advanced entities": "/entities-advanced", - "Entity interfaces": "/federated-types/interfaces", - "Migrating from schema stitching": "/migrating-from-stitching" + "Federated Directives": "/federated-types/federated-directives", + "Sharing Types (Value Types)": "/federated-types/sharing-types", + "Introduction to Entities": "/entities", + "Advanced Entities": "/entities-advanced", + "Entity Interfaces": "/federated-types/interfaces", + "Migrating from Schema Stitching": "/migrating-from-stitching" }, "Managed Federation": { "Overview": "/managed-federation/overview", "Setup": "/managed-federation/setup", "Uplink": "/managed-federation/uplink", - "Federated schema checks": "/managed-federation/federated-schema-checks", - "Deployment best practices": "/managed-federation/deployment", - "Opt-in error reporting": "/managed-federation/error-reporting", - "Studio features": "https://www.apollographql.com/docs/graphos/graphs/federated-graphs" + "Federated Schema Checks": "/managed-federation/federated-schema-checks", + "Deployment Best Practices": "/managed-federation/deployment", + "Opt-In Error Reporting": "/managed-federation/error-reporting", + "Studio Features": "https://www.apollographql.com/docs/graphos/graphs/federated-graphs" }, "Performance": { "Caching": "/performance/caching", "Monitoring": "/performance/monitoring", - "Query plans": "/query-plans" + "Query Plans": "/query-plans" }, "Debugging & Metrics": { - "Error codes": "/errors", - "Composition hints": "/hints", - "Federated trace data": "/metrics", + "Error Codes": "/errors", + "Composition Hints": "/hints", + "Federated Trace Data": "/metrics", "OpenTelemetry": "/opentelemetry" }, "API Reference": { - "Subgraph specification": "/subgraph-spec", + "Subgraph Specification": "/subgraph-spec", "@apollo/subgraph": "https://apollographql.com/docs/apollo-server/using-federation/api/apollo-subgraph", "@apollo/gateway": "https://apollographql.com/docs/apollo-server/using-federation/api/apollo-gateway" }, "Moving from Federation 1": { "Changes from Federation 1": "/federation-2/new-in-federation-2", - "Steps to move": "/federation-2/moving-to-federation-2", - "Backward compatibility": "/federation-2/backward-compatibility" + "Steps to Move": "/federation-2/moving-to-federation-2", + "Backward Compatibility": "/federation-2/backward-compatibility" } } } diff --git a/docs/source/entities-advanced.mdx b/docs/source/entities-advanced.mdx index 0069d9ed2..8bbad6144 100644 --- a/docs/source/entities-advanced.mdx +++ b/docs/source/entities-advanced.mdx @@ -1,5 +1,7 @@ --- -title: Advanced topics on federated entities +title: Advanced Topics on Federated Entities +subtitle: Learn about advanced use cases for entities +description: Explore advanced use cases for entities in a federated GraphQL architecture, including compound keys, migrating entity fields, and contributing computed fields. --- import ProgressiveOverrideEnterprise from '../shared/progressive-override-enterprise.mdx'; diff --git a/docs/source/entities.mdx b/docs/source/entities.mdx index 8ba7795b1..86efa52dc 100644 --- a/docs/source/entities.mdx +++ b/docs/source/entities.mdx @@ -1,6 +1,7 @@ --- title: Entities in Apollo Federation -description: Resolve types across multiple subgraphs +subtitle: Learn how to resolve federated types across multiple subgraphs +description: Learn to define, contribute to, and reference object types that resolve their fields across multiple subgraphs in a federated GraphQL architecture. --- diff --git a/docs/source/errors.mdx b/docs/source/errors.mdx index 2e3955dc7..390047304 100644 --- a/docs/source/errors.mdx +++ b/docs/source/errors.mdx @@ -1,6 +1,7 @@ --- -title: Federation error codes -description: Learn the error codes you can receive if composition fails. +title: Apollo Federation Error Codes +subtitle: Reference for composition error codes +description: Reference the error codes encountered during Apollo Federation schema composition, identifying root causes and solutions for GraphQL debugging. toc: false --- diff --git a/docs/source/federated-types/composition.mdx b/docs/source/federated-types/composition.mdx index b11ab2a36..80cb5ea16 100644 --- a/docs/source/federated-types/composition.mdx +++ b/docs/source/federated-types/composition.mdx @@ -1,6 +1,7 @@ --- -title: Schema composition -description: In Apollo Federation +title: Schema Composition +subtitle: Learn how subgraph schemas combine into a supergraph schema +description: Learn about schema composition in a federated GraphQL architecture. Explore strategies for handling conflicting types and directives. --- In Apollo Federation, _composition_ is the process of combining a set of [subgraph schemas](./overview/#subgraph-schemas) into a [supergraph schema](./overview/#supergraph-schema): diff --git a/docs/source/federated-types/federated-directives.mdx b/docs/source/federated-types/federated-directives.mdx index c265649c3..59ba58dee 100644 --- a/docs/source/federated-types/federated-directives.mdx +++ b/docs/source/federated-types/federated-directives.mdx @@ -1,5 +1,7 @@ --- -title: Federation-specific GraphQL directives +title: Apollo Federation Directives +subtitle: Reference for Apollo Federation specific GraphQL directives +description: Reference for GraphQL federation directives including @key, @extends, @sharable, @override, @requires and more. --- import ProgressiveOverrideEnterprise from '../../shared/progressive-override-enterprise.mdx'; diff --git a/docs/source/federated-types/interfaces.mdx b/docs/source/federated-types/interfaces.mdx index 4eb176886..8231ea5d1 100644 --- a/docs/source/federated-types/interfaces.mdx +++ b/docs/source/federated-types/interfaces.mdx @@ -1,6 +1,7 @@ --- -title: Entity interfaces -description: Add entity fields polymorphically +title: Entity Interfaces +subtitle: Add entity fields polymorphically +description: Discover how to efficiently add polymorphic fields to GraphQL interfaces using Apollo Federation's Entity Interfaces and the @interfaceObject directive. minVersion: 2.3 --- diff --git a/docs/source/federated-types/overview.mdx b/docs/source/federated-types/overview.mdx index b2cfffd12..91ee1c0c4 100644 --- a/docs/source/federated-types/overview.mdx +++ b/docs/source/federated-types/overview.mdx @@ -1,6 +1,7 @@ --- -title: Federated schemas -description: Overview +title: Federated Schemas +subtitle: Learn about the different types of GraphQL schemas +description: Learn about subgraph, supergraph, and API schemas in federated GraphQL architectures. --- A federated supergraph uses multiple "types" of GraphQL schemas: diff --git a/docs/source/federated-types/sharing-types.mdx b/docs/source/federated-types/sharing-types.mdx index ee1b8485a..b67e03e1f 100644 --- a/docs/source/federated-types/sharing-types.mdx +++ b/docs/source/federated-types/sharing-types.mdx @@ -1,6 +1,7 @@ --- -title: Value types in Apollo Federation -description: Share types and fields across multiple subgraphs +title: Value Types in Apollo Federation +subtitle: Share types and fields across multiple subgraphs +description: Learn how to share GraphQL types and fields across subgraphs with Apollo Federation. --- In a federated graph, it's common to want to reuse a GraphQL type across multiple [subgraphs](../building-supergraphs/subgraphs-overview/). diff --git a/docs/source/federation-2/backward-compatibility.mdx b/docs/source/federation-2/backward-compatibility.mdx index f7ca8d121..c1effe793 100644 --- a/docs/source/federation-2/backward-compatibility.mdx +++ b/docs/source/federation-2/backward-compatibility.mdx @@ -1,6 +1,7 @@ --- -title: Backward compatibility in Federation 2 -description: FAQ +title: Backward Compatibility in Apollo Federation 2 +subtitle: Navigating the transition from Apollo Federation 1 to Federation 2 +description: Frequently asked questions when transitioning from Apollo Federation 1 to Federation 2. --- ## Is official support ending for `@apollo/gateway` v0.x? diff --git a/docs/source/federation-2/moving-to-federation-2.mdx b/docs/source/federation-2/moving-to-federation-2.mdx index 7138675d8..e0fb765c4 100644 --- a/docs/source/federation-2/moving-to-federation-2.mdx +++ b/docs/source/federation-2/moving-to-federation-2.mdx @@ -1,6 +1,7 @@ --- title: Moving to Apollo Federation 2 -description: Upgrade your supergraph incrementally at any pace +subtitle: Upgrade from Apollo Federation 1 to Federation 2 +description: Upgrade from Apollo Federation 1 to Federation 2 to benefit from improved composition logic and schema flexibility. --- > 📣 If you haven't yet, [see what's new in Federation 2.](./new-in-federation-2/) diff --git a/docs/source/federation-2/new-in-federation-2.mdx b/docs/source/federation-2/new-in-federation-2.mdx index 22932a625..60f76f40f 100644 --- a/docs/source/federation-2/new-in-federation-2.mdx +++ b/docs/source/federation-2/new-in-federation-2.mdx @@ -1,5 +1,7 @@ --- -title: Changes from Federation 1 to Federation 2 +title: Changes from Apollo Federation 1 +subtitle: Learn what's new in Apollo Federation 2 +description: Explore the improvements and changes from Apollo Federation 1 to Federation 2, enhancing flexibility and schema composition in GraphQL. --- Apollo Federation 2 provides developer experience improvements to the original specification for Apollo Federation (called _Federation 1_ in these docs). If your organization has an existing Federation 1 graph, this article summarizes the benefits of [moving to Federation 2](./moving-to-federation-2/). diff --git a/docs/source/federation-versions.mdx b/docs/source/federation-versions.mdx index ae44c5afc..68a4a4287 100644 --- a/docs/source/federation-versions.mdx +++ b/docs/source/federation-versions.mdx @@ -1,6 +1,7 @@ --- -title: Federation version changelog -description: Understand changes between federation versions +title: Apollo Federation Changelog +subtitle: Understand changes between Apollo Federation versions +description: Understand changes between Apollo Federation major and minor versions. --- This article describes notable changes and additions introduced in each minor version release of Apollo Federation. Most of these changes involve additions or modifications to [federation-specific directives](./federated-types/federated-directives/). diff --git a/docs/source/hints.mdx b/docs/source/hints.mdx index 94e5694d2..c55371ea6 100644 --- a/docs/source/hints.mdx +++ b/docs/source/hints.mdx @@ -1,5 +1,7 @@ --- -title: Composition hints +title: Composition Hints +subtitle: Reference for composition hints +description: Learn about hints flagged during Apollo Federation schema composition using GraphOS Studio or the Rover CLI. --- When you successfully [compose](./federated-types/composition) the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, the composition process can flag potential improvements or hints. Hints are violations of the [GraphOS schema linter's](/graphos/delivery/schema-linter) [composition rules](/graphos/delivery/linter-rules#composition-rules). You can review them on the [Checks](/graphos/delivery/schema-checks) page in GraphOS Studio or via the [Rover CLI](/rover/). diff --git a/docs/source/index.mdx b/docs/source/index.mdx index 4a98694d2..6e9010672 100644 --- a/docs/source/index.mdx +++ b/docs/source/index.mdx @@ -1,7 +1,7 @@ --- 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 a microservices architecture +description: Learn how Apollo Federation can help you declaratively combine your services into a unified, federated GraphQL API using a microservices architecture. --- ## What is Apollo Federation? diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index f3aa52cbc..687ab6bf1 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -1,7 +1,7 @@ --- -title: Deployment 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 +description: Best practices and workflows for deploying a federated GraphQL API with Apollo Federation and GraphOS. --- When rolling out changes to a [subgraph](../building-supergraphs/subgraphs-overview/), we recommend the following workflow: diff --git a/docs/source/managed-federation/error-reporting.mdx b/docs/source/managed-federation/error-reporting.mdx index c8c730eaf..5b340e177 100644 --- a/docs/source/managed-federation/error-reporting.mdx +++ b/docs/source/managed-federation/error-reporting.mdx @@ -1,5 +1,7 @@ --- -title: Opt-in error reporting for managed federation +title: Opt-In Error Reporting for Managed Federation +subtitle: Configure out-of-band reporting +description: Learn how to configure your managed gateway to send error reports to Apollo via out-of-band reporting, improving performance and reliability. --- You can configure your managed gateway to send error reports to Apollo via _out-of-band reporting_. These reports help Apollo improve the performance and reliability of managed federation. diff --git a/docs/source/managed-federation/federated-schema-checks.mdx b/docs/source/managed-federation/federated-schema-checks.mdx index 91d65a8e8..839d1a0d5 100644 --- a/docs/source/managed-federation/federated-schema-checks.mdx +++ b/docs/source/managed-federation/federated-schema-checks.mdx @@ -1,5 +1,7 @@ --- -title: Federated schema checks +title: Federated Schema Checks +subtitle: Use schema checks for independent and safe subgraph development +description: Use GraphOS schema checks and the Rover CLI to enable independent and safe subgraph development in federated GraphQL architectures. --- diff --git a/docs/source/managed-federation/overview.mdx b/docs/source/managed-federation/overview.mdx index b8987b655..96fabad1f 100644 --- a/docs/source/managed-federation/overview.mdx +++ b/docs/source/managed-federation/overview.mdx @@ -1,7 +1,7 @@ --- -title: Managed federation overview -description: Let Apollo GraphOS manage CI/CD of your supergraph including schema validation, composition, and configuration. +title: Managed Federation Overview subtitle: Manage supergraph CI/CD with Apollo GraphOS +description: Use Apollo GraphOS to manage your supergraph including schema validation, composition, and configuration. --- import ManagedFederationDiagram from '../../shared/diagrams/managed-federation.mdx'; diff --git a/docs/source/managed-federation/setup.mdx b/docs/source/managed-federation/setup.mdx index 1219b52ed..e8b14acb5 100644 --- a/docs/source/managed-federation/setup.mdx +++ b/docs/source/managed-federation/setup.mdx @@ -1,5 +1,7 @@ --- -title: Setting up managed federation +title: Setting Up Managed Federation +subtitle: Connect your supergraph to Apollo GraphOS +description: Learn how to connect your supergraph to the Apollo GraphOS platform for managed GraphQL federation. --- This article describes how to connect your supergraph to [Apollo GraphOS](/graphos/) to enable managed federation features. diff --git a/docs/source/managed-federation/uplink.mdx b/docs/source/managed-federation/uplink.mdx index 08c471f92..7a404811a 100644 --- a/docs/source/managed-federation/uplink.mdx +++ b/docs/source/managed-federation/uplink.mdx @@ -1,6 +1,7 @@ --- title: Apollo Uplink -description: Fetch your managed router's configuration +subtitle: Fetch your managed router's configuration +description: Learn how to configure Apollo Uplink for managed GraphQL federation, including polling behavior and Uplink URLs. --- 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: diff --git a/docs/source/metrics.md b/docs/source/metrics.md index bb96d9cfc..75aa0634d 100644 --- a/docs/source/metrics.md +++ b/docs/source/metrics.md @@ -1,6 +1,7 @@ --- -title: Federated trace data -description: Reporting fine-grained performance metrics +title: Federated Trace Data +subtitle: Reporting fine-grained performance metrics +description: Explore how federated traces enable fine-grained performance metrics reporting. Learn about the reporting flow and how tracing data is exposed and aggregated. --- One of the many benefits of using GraphQL as an API layer is that it enables fine-grained, field-level [tracing](/graphos/metrics/#resolver-level-traces) of every executed operation. The [GraphOS platform](/graphos/) can consume and aggregate these traces to provide detailed insights into your supergraph's usage and performance. diff --git a/docs/source/migrating-from-stitching.md b/docs/source/migrating-from-stitching.md index 770968cb4..6f7bf2d19 100644 --- a/docs/source/migrating-from-stitching.md +++ b/docs/source/migrating-from-stitching.md @@ -1,6 +1,7 @@ --- -title: Migrating from schema stitching -description: How to move your services to Apollo Federation +title: Migrating from Schema Stitching +subtitle: How to transition to Apollo Federation +description: Learn how to smoothly transition from schema stitching to Apollo Federation for your distributed federated GraphQL services. --- If you have a distributed graph that uses schema stitching, follow the diff --git a/docs/source/opentelemetry.mdx b/docs/source/opentelemetry.mdx index fe97fcb9e..9a6ed3cc4 100644 --- a/docs/source/opentelemetry.mdx +++ b/docs/source/opentelemetry.mdx @@ -1,6 +1,8 @@ --- title: OpenTelemetry in Apollo Federation sidebar_title: OpenTelemetry +subtitle: Configure your federated graph to emit logs, traces, and metrics +description: Learn how to configure your federated GraphQL services to generate and process telemetry data, including logs, traces, and metrics. --- [OpenTelemetry](https://opentelemetry.io/) is a collection of open-source tools for generating and processing telemetry data (such as logs, traces, and metrics) from different systems in a generic and consistent way. diff --git a/docs/source/performance/caching.mdx b/docs/source/performance/caching.mdx index ba97b5b7d..4a2a14595 100644 --- a/docs/source/performance/caching.mdx +++ b/docs/source/performance/caching.mdx @@ -1,6 +1,8 @@ --- -title: Server-side caching +title: Server-Side Caching sidebar_title: Caching +subtitle: Configure server-side caching with Apollo Server-based subgraphs +description: Learn about implementing server-side caching in a federated GraphQL architecture, including using and overriding cache hints with subgraphs. --- diff --git a/docs/source/performance/monitoring.mdx b/docs/source/performance/monitoring.mdx index 232a40add..6ac3c534f 100644 --- a/docs/source/performance/monitoring.mdx +++ b/docs/source/performance/monitoring.mdx @@ -1,6 +1,8 @@ --- -title: Monitoring a federated graph +title: Monitoring a Federated Graph sidebar_title: Monitoring +subtitle: Learn about operation metrics and monitoring strategies +description: Discover Apollo managed federation features that enhance monitoring and debugging capabilities for your federated GraphQL API. --- As with any distributed architecture, a federated graph introduces more complexity than its monolithic counterpart. To help address this complexity and improve reliability, you should make sure that your federated graph has proper observability, monitoring, and automation in place. diff --git a/docs/source/query-plans.mdx b/docs/source/query-plans.mdx index b720c8dd9..1964b3694 100644 --- a/docs/source/query-plans.mdx +++ b/docs/source/query-plans.mdx @@ -1,6 +1,7 @@ --- -title: Query plans -description: How your router plans operations across subgraphs +title: Query Plans +subtitle: Learn how your router orchestrates operations across subgraphs +description: Learn how your router orchestrates operations across subgraphs, ensuring seamless data retrieval for complex GraphQL operations in a federated architecture. --- Learn about query plans to help you debug advanced use cases of Apollo Federation. diff --git a/docs/source/quickstart/local-composition.mdx b/docs/source/quickstart/local-composition.mdx index e8b784e1b..641e5f957 100644 --- a/docs/source/quickstart/local-composition.mdx +++ b/docs/source/quickstart/local-composition.mdx @@ -1,6 +1,7 @@ --- -title: Federation quickstart -description: Part 3 - Local composition +title: Apollo Federation Quickstart +subtitle: "Part 3: Local composition" +description: Compose your federated GraphQL schema locally using the Rover CLI. After composing the schema, provide it to your graph router. --- [Back in Part 2](./studio-composition/), we used managed federation with GraphOS Studio to compose our router's supergraph schema. Next, let's try out composing locally with the Rover CLI. diff --git a/docs/source/quickstart/local-subgraphs.mdx b/docs/source/quickstart/local-subgraphs.mdx index 727a8247e..6b09ed3e4 100644 --- a/docs/source/quickstart/local-subgraphs.mdx +++ b/docs/source/quickstart/local-subgraphs.mdx @@ -1,6 +1,7 @@ --- -title: Federation quickstart -description: Part 4 - Working with subgraphs +title: Apollo Federation Quickstart +subtitle: "Part 4: Working with subgraphs" +description: Use GraphQL Federation to join fields from different subgraphs into a federated type. --- 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. @@ -126,4 +127,4 @@ With schema checks, you can check whether some changes you want to make to your --- -Congratulations, you've completed the federation quickstart! \ No newline at end of file +Congratulations, you've completed the Federation Quickstart! \ No newline at end of file diff --git a/docs/source/quickstart/setup.mdx b/docs/source/quickstart/setup.mdx index f0213fc05..f4e81f8df 100644 --- a/docs/source/quickstart/setup.mdx +++ b/docs/source/quickstart/setup.mdx @@ -1,6 +1,7 @@ --- -title: Federation 2 quickstart -description: Part 1 - Project setup +title: Apollo Federation Quickstart +subtitle: "Part 1: Project setup" +description: Get started with GraphQL Federation, including setting up Apollo tools, obtaining subgraph schemas, and composing a supergraph in GraphOS Studio. --- Hello! This tutorial gets you up and running quickly with an Apollo Federation 2 supergraph. diff --git a/docs/source/quickstart/studio-composition.mdx b/docs/source/quickstart/studio-composition.mdx index 79c3cb020..65d74e467 100644 --- a/docs/source/quickstart/studio-composition.mdx +++ b/docs/source/quickstart/studio-composition.mdx @@ -1,6 +1,7 @@ --- -title: Federation 2 quickstart -description: Part 2 - Composition in GraphOS Studio +title: Apollo Federation Quickstart +subtitle: "Part 2: Composition in GraphOS Studio" +description: Compose your federated GraphQL API schema with GraphOS Studio. Register you subgraph schemas and authenticate your graph router. --- Now that our project and tools are set up, we can start composing our supergraph schema with GraphOS Studio. diff --git a/docs/source/subgraph-spec.mdx b/docs/source/subgraph-spec.mdx index 0ca5f7b7b..342f6e97e 100644 --- a/docs/source/subgraph-spec.mdx +++ b/docs/source/subgraph-spec.mdx @@ -1,6 +1,7 @@ --- -title: Apollo Federation subgraph specification -description: For adding subgraph support to GraphQL server libraries +title: Apollo Federation Subgraph Specification +subtitle: Subgraph specification reference for server library developers +description: Learn about Apollo Federation 2 subgraph specifications, enhanced introspection, and entity field resolution for 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](./building-supergraphs/supported-subgraphs/), such as Apollo Server.