From 4c6c268d12557880022d92ec753feaeab78a9cd3 Mon Sep 17 00:00:00 2001 From: Edward Huang Date: Wed, 16 Oct 2024 09:07:52 -0700 Subject: [PATCH] docs: main docs replatform (#3169) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Merge docs content of new docs site --------- Co-authored-by: Maria Elisabeth Schreiber --- .cspell/cspell-dict.txt | 5 + .github/workflows/docs-publish.yml | 16 - docs/shared/enterprise-directive.mdx | 2 +- .../progressive-override-enterprise.mdx | 2 +- .../compatible-subgraphs.md | 412 +++-- .../compatible-subgraphs.mdx | 1645 +++++++++++++++++ docs/source/building-supergraphs/router.mdx | 40 - .../subgraph-specific-fields.mdx | 84 + .../subgraphs-overview.mdx | 141 -- docs/source/entities/contribute-fields.mdx | 4 +- docs/source/entities/define-advanced-keys.mdx | 4 +- docs/source/entities/handling-n-plus-one.mdx | 4 +- docs/source/entities/index.mdx | 161 -- docs/source/entities/interfaces.mdx | 14 +- docs/source/entities/migrate-fields.mdx | 8 +- docs/source/entities/use-contexts.mdx | 2 +- docs/source/errors.mdx | 2 +- docs/source/federated-schemas/composition.mdx | 561 ------ .../federated-directives.mdx | 58 +- docs/source/federated-schemas/index.mdx | 232 --- .../federated-schemas/sharing-types.mdx | 645 ------- .../federation-2/backward-compatibility.mdx | 12 +- .../federation-2/moving-to-federation-2.mdx | 36 +- .../federation-2/new-in-federation-2.mdx | 36 +- docs/source/federation-versions.mdx | 36 +- docs/source/hints.mdx | 6 +- docs/source/index.mdx | 173 -- docs/source/managed-federation/deployment.mdx | 32 +- .../federated-schema-checks.mdx | 4 +- docs/source/managed-federation/overview.mdx | 8 +- docs/source/managed-federation/setup.mdx | 12 +- docs/source/managed-federation/uplink.mdx | 16 +- docs/source/metrics.mdx | 81 + docs/source/migrating-from-stitching.md | 2 +- docs/source/migrating-from-stitching.mdx | 188 ++ docs/source/opentelemetry.mdx | 4 +- docs/source/performance/monitoring.mdx | 6 +- docs/source/query-plans.mdx | 29 +- docs/source/quickstart.mdx | 609 ------ docs/source/subgraph-spec.mdx | 8 +- 40 files changed, 2393 insertions(+), 2947 deletions(-) delete mode 100644 .github/workflows/docs-publish.yml create mode 100644 docs/source/building-supergraphs/compatible-subgraphs.mdx delete mode 100644 docs/source/building-supergraphs/router.mdx create mode 100644 docs/source/building-supergraphs/subgraph-specific-fields.mdx delete mode 100644 docs/source/building-supergraphs/subgraphs-overview.mdx delete mode 100644 docs/source/entities/index.mdx delete mode 100644 docs/source/federated-schemas/composition.mdx delete mode 100644 docs/source/federated-schemas/index.mdx delete mode 100644 docs/source/federated-schemas/sharing-types.mdx delete mode 100644 docs/source/index.mdx create mode 100644 docs/source/metrics.mdx create mode 100644 docs/source/migrating-from-stitching.mdx delete mode 100644 docs/source/quickstart.mdx diff --git a/.cspell/cspell-dict.txt b/.cspell/cspell-dict.txt index 2f8435806..f0d5db4f1 100644 --- a/.cspell/cspell-dict.txt +++ b/.cspell/cspell-dict.txt @@ -45,6 +45,7 @@ condiditions correcly cyclesf Cypher +dariuszkuc dedented Dedupe defered @@ -61,6 +62,7 @@ Didnt diretive doesn Dont +dotansimha effecient elimiate elts @@ -81,6 +83,7 @@ follwoing fooz Fragmentization fufilled +ghostdogpr GHSA Gmsuh gqlgen @@ -191,6 +194,7 @@ resovable Reviwed Rhai righ +rmosolgo rulesof runtimes samee @@ -273,6 +277,7 @@ upgader Upgrader upgrader uppper +Urigo uuidv vals verison diff --git a/.github/workflows/docs-publish.yml b/.github/workflows/docs-publish.yml deleted file mode 100644 index 9f991692d..000000000 --- a/.github/workflows/docs-publish.yml +++ /dev/null @@ -1,16 +0,0 @@ -name: Deploy docs to production - -on: - push: - branches: - - main - - version-0.x - paths: - - docs/** - -jobs: - publish: - uses: apollographql/docs/.github/workflows/publish.yml@main - secrets: - NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }} - NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }} diff --git a/docs/shared/enterprise-directive.mdx b/docs/shared/enterprise-directive.mdx index 7933a7e85..76547cd2b 100644 --- a/docs/shared/enterprise-directive.mdx +++ b/docs/shared/enterprise-directive.mdx @@ -1,5 +1,5 @@ -This directive is an [Enterprise feature](/router/enterprise-features) of the GraphOS Router and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). If your organization doesn't have an Enterprise plan, you can test it out by signing up for a free [Enterprise trial](/graphos/org/plans/#enterprise-trials). +This directive is an [Enterprise feature](https://www.apollographql.com/pricing) of the GraphOS Router and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). If your organization doesn't have an Enterprise plan, you can test it out by signing up for a free [Enterprise trial](https://studio.apollographql.com/signup?referrer=docs). \ No newline at end of file diff --git a/docs/shared/progressive-override-enterprise.mdx b/docs/shared/progressive-override-enterprise.mdx index afc54ed22..332e87701 100644 --- a/docs/shared/progressive-override-enterprise.mdx +++ b/docs/shared/progressive-override-enterprise.mdx @@ -1,5 +1,5 @@ -Progressive `@override` is an [Enterprise feature](/router/enterprise-features) of the GraphOS Router and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). If your organization doesn't have an Enterprise plan, you can test it out by signing up for a free [Enterprise trial](/graphos/org/plans/#enterprise-trials). +Progressive `@override` is an [Enterprise feature](https://www.apollographql.com/pricing) of the GraphOS Router and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). If your organization doesn't have an Enterprise plan, you can test it out by signing up for a free [Enterprise trial](https://studio.apollographql.com/signup?referrer=docs). \ No newline at end of file diff --git a/docs/source/building-supergraphs/compatible-subgraphs.md b/docs/source/building-supergraphs/compatible-subgraphs.md index 95ad729eb..6ec93a16e 100644 --- a/docs/source/building-supergraphs/compatible-subgraphs.md +++ b/docs/source/building-supergraphs/compatible-subgraphs.md @@ -10,12 +10,12 @@ The following open-source GraphQL server libraries and hosted solutions support ## Table Legend -| Icon | Description | -| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -| Maintained by Apollo | Maintained by Apollo | -| 🟒 | Functionality is supported | -| ❌ | Critical functionality is NOT supported | -| πŸ”² | Additional federation functionality is NOT supported | +| Icon | Description | +| --- | --- | +| Maintained by Apollo | Maintained by Apollo | +| 🟒 | Functionality is supported | +| ❌ | Critical functionality is NOT supported | +| πŸ”² | Additional federation functionality is NOT supported | ## Ballerina @@ -27,12 +27,13 @@ The following open-source GraphQL server libraries and hosted solutions support Federation 2 Support - - - Ballerina GraphQL Module - - - A spec-compliant, production-ready, Standard Library module for building and interacting with GraphQL APIs using Ballerina.
+ + + Ballerina GraphQL Module + + + + A spec-compliant, production-ready, Standard Library module for building and interacting with GraphQL APIs using Ballerina.

Github: ballerina-platform/module-ballerina-graphql

@@ -78,12 +79,13 @@ Last Release: 2024-05-03
Federation 2 Support - - - GraphQL for .NET - - - GraphQL for .NET
+ + + GraphQL for .NET + + + + GraphQL for .NET

Github: graphql-dotnet/graphql-dotnet

@@ -116,11 +118,12 @@ Last Release: 2024-02-06
- - Hot Chocolate - - - Open-source GraphQL server for the Microsoft .NET platform that takes the complexity away and lets you focus on delivering the next big thing.
+ + Hot Chocolate + + + + Open-source GraphQL server for the Microsoft .NET platform that takes the complexity away and lets you focus on delivering the next big thing.

Github: ChilliCream/graphql-platform

@@ -167,12 +170,13 @@ Federation Library: Absinthe - - - The GraphQL toolkit for Elixir
+ + + Absinthe + + + + The GraphQL toolkit for Elixir

Github: absinthe-graphql/absinthe

@@ -219,12 +223,13 @@ Federation Library: Federation 2 Support - - - gqlgen - - - go generate based graphql server library
+ + + gqlgen + + + + go generate based graphql server library

Github: 99designs/gqlgen

@@ -257,11 +262,12 @@ Last Release: 2024-03-11
- - GraphQL Go (fork) - - - This is a fork of graphql-go/graphql that adds Federation support
+ + GraphQL Go (fork) + + + + This is a fork of graphql-go/graphql that adds Federation support

Github: dariuszkuc/graphql

@@ -307,12 +313,13 @@ Last Release: 2022-11-11
Federation 2 Support - - - dgs-framework - - - GraphQL for Java with Spring Boot made easy.
+ + + dgs-framework + + + + GraphQL for Java with Spring Boot made easy.

Github: netflix/dgs-framework

@@ -347,11 +354,12 @@ Federation Library: ap - - GraphQL Java Kickstart (Spring Boot) - - - GraphQL and GraphiQL Spring Framework Boot Starters - Forked from oembedler/graphql-spring-boot due to inactivity.
+ + GraphQL Java Kickstart (Spring Boot) + + + + GraphQL and GraphiQL Spring Framework Boot Starters - Forked from oembedler/graphql-spring-boot due to inactivity.

Github: graphql-java-kickstart/graphql-spring-boot

@@ -386,11 +394,12 @@ Federation Library: ap - - GraphQL Kotlin - - - Libraries for running GraphQL in Kotlin
+ + GraphQL Kotlin + + + + Libraries for running GraphQL in Kotlin

Github: ExpediaGroup/graphql-kotlin

@@ -424,11 +433,12 @@ Core Library: GraphQL Jav - - Spring GraphQL - - - Spring Integration for GraphQL
+ + Spring GraphQL + + + + Spring Integration for GraphQL

Github: spring-projects/spring-graphql

@@ -476,12 +486,13 @@ Federation Library: ap Federation 2 Support - - - Apollo Server - - - 🌍  Spec-compliant and production ready JavaScript GraphQL server that lets you develop in a schema-first way. Built for Express, Connect, Hapi, Koa, and more.
+ + + Apollo Server + + + + 🌍  Spec-compliant and production ready JavaScript GraphQL server that lets you develop in a schema-first way. Built for Express, Connect, Hapi, Koa, and more.

Github: apollographql/apollo-server  Maintained by Apollo

@@ -516,11 +527,12 @@ Federation Library: Apo - - express-graphql - - - Create a GraphQL HTTP server with Express.
+ + express-graphql + + + + Create a GraphQL HTTP server with Express.

Github: graphql/express-graphql

@@ -555,11 +567,12 @@ Federation Library: Apo - - GraphQL Yoga - - - The fully-featured GraphQL server with focus on easy setup, performance and great developer experience.
+ + GraphQL Yoga + + + + The fully-featured GraphQL server with focus on easy setup, performance and great developer experience.

Github: dotansimha/graphql-yoga

@@ -594,11 +607,12 @@ Federation Library: Apo - - GraphQL Helix - - - A highly evolved and framework-agnostic GraphQL HTTP server.
+ + GraphQL Helix + + + + A highly evolved and framework-agnostic GraphQL HTTP server.

Github: contra/graphql-helix

@@ -633,11 +647,12 @@ Federation Library: Apo - - Mercurius - - - Implement GraphQL servers and gateways with Fastify
+ + Mercurius + + + + Implement GraphQL servers and gateways with Fastify

Github: mercurius-js/mercurius

@@ -672,11 +687,12 @@ Federation Library: Apo - - NestJS (code first) - - - A progressive Node.js framework for building efficient, reliable and scalable server-side applications.
+ + NestJS (code first) + + + + A progressive Node.js framework for building efficient, reliable and scalable server-side applications.

Github: nestjs/graphql

@@ -711,11 +727,12 @@ Federation Library: Apo - - NestJS (SDL First) - - - A progressive Node.js framework for building efficient, reliable and scalable server-side applications.
+ + NestJS (SDL First) + + + + A progressive Node.js framework for building efficient, reliable and scalable server-side applications.

Github: nestjs/graphql

@@ -750,11 +767,12 @@ Federation Library: Apo - - Pothos GraphQL - - - Plugin based GraphQL schema builder that makes building graphql schemas with TypeScript easy, fast and enjoyable.
+ + Pothos GraphQL + + + + Plugin based GraphQL schema builder that makes building graphql schemas with TypeScript easy, fast and enjoyable.

Github: hayes/pothos

@@ -801,12 +819,13 @@ Core Library: GraphQL.js
Federation 2 Support - - - Lighthouse (Laravel) - - - A framework for serving GraphQL from Laravel
+ + + Lighthouse (Laravel) + + + + A framework for serving GraphQL from Laravel

Github: nuwave/lighthouse

@@ -840,11 +859,12 @@ Core Library: webonyx/graphql-p - - GraphQL PHP - - - PHP implementation of the GraphQL specification based on the reference implementation in JavaScript
+ + GraphQL PHP + + + + PHP implementation of the GraphQL specification based on the reference implementation in JavaScript

Github: webonyx/graphql-php

@@ -891,12 +911,13 @@ Federation Library: Ariadne - - - Python library for implementing GraphQL servers using schema-first approach.
+ + + Ariadne + + + + Python library for implementing GraphQL servers using schema-first approach.

Github: mirumee/ariadne

@@ -930,11 +951,12 @@ Core Library: GraphQL-c - - Graphene - - - GraphQL framework for Python
+ + Graphene + + + + GraphQL framework for Python

Github: graphql-python/graphene

@@ -969,11 +991,12 @@ Federation Library: Strawberry - - - A GraphQL library for Python that leverages type annotations πŸ“
+ + Strawberry + + + + A GraphQL library for Python that leverages type annotations πŸ“

Github: strawberry-graphql/strawberry

@@ -1020,12 +1043,13 @@ Core Library: GraphQL-c Federation 2 Support - - - GraphQL Ruby - - - Ruby implementation of GraphQL
+ + + GraphQL Ruby + + + + Ruby implementation of GraphQL

Github: rmosolgo/graphql-ruby

@@ -1072,12 +1096,13 @@ Federation Library: G Federation 2 Support - - - async-graphql - - - A GraphQL server library implemented in Rust
+ + + async-graphql + + + + A GraphQL server library implemented in Rust

Github: async-graphql/async-graphql

@@ -1123,12 +1148,13 @@ Last Release: 2022-11-28
Federation 2 Support - - - Caliban - - - Functional GraphQL library for Scala
+ + + Caliban + + + + Functional GraphQL library for Scala

Github: ghostdogpr/caliban

@@ -1161,11 +1187,12 @@ Last Release: 2024-04-16
- - Sangria - - - Scala GraphQL implementation
+ + Sangria + + + + Scala GraphQL implementation

Github: sangria-graphql/sangria

@@ -1212,12 +1239,13 @@ Federation Library: Graphiti - - - The Swift GraphQL Schema framework for macOS and Linux
+ + + Graphiti + + + + The Swift GraphQL Schema framework for macOS and Linux

Github: GraphQLSwift/Graphiti

@@ -1263,12 +1291,13 @@ Last Release: 2023-11-15
Federation 2 Support - - - AWS AppSync - - - Serverless GraphQL and Pub/Sub APIs
+ + + AWS AppSync + + + + Serverless GraphQL and Pub/Sub APIs


@@ -1296,11 +1325,12 @@ Last Release: 2023-11-15
- - Dgraph - - - Dgraph is the native GraphQL database with a graph backend. It is open-source, scalable, distributed, highly available and lightning fast.
+ + Dgraph + + + + Dgraph is the native GraphQL database with a graph backend. It is open-source, scalable, distributed, highly available and lightning fast.


@@ -1328,11 +1358,12 @@ Last Release: 2023-11-15
- - Grafbase - - - The GraphQL platform
+ + Grafbase + + + + The GraphQL platform

Github: grafbase/grafbase

@@ -1365,11 +1396,12 @@ Last Release: 2024-02-23
- - GraphQL Mesh - - - Executable GraphQL schema from multiple data sources, query anything, run anywhere.
+ + GraphQL Mesh + + + + Executable GraphQL schema from multiple data sources, query anything, run anywhere.

Github: Urigo/graphql-mesh

@@ -1402,11 +1434,12 @@ Last Release: 2024-04-30
- - Neo4J Graph Database - - - A GraphQL to Cypher query execution layer for Neo4j and JavaScript GraphQL implementations.
+ + Neo4J Graph Database + + + + A GraphQL to Cypher query execution layer for Neo4j and JavaScript GraphQL implementations.

Github: neo4j/graphql

@@ -1441,11 +1474,12 @@ Federation Library: Apo - - StepZen, an IBM Company - - - Build GraphQL APIs for all your data in a declarative way. Federate across any data source, including GraphQL.
+ + StepZen, an IBM Company + + + + Build GraphQL APIs for all your data in a declarative way. Federate across any data source, including GraphQL.


diff --git a/docs/source/building-supergraphs/compatible-subgraphs.mdx b/docs/source/building-supergraphs/compatible-subgraphs.mdx new file mode 100644 index 000000000..813735cdd --- /dev/null +++ b/docs/source/building-supergraphs/compatible-subgraphs.mdx @@ -0,0 +1,1645 @@ +--- +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. + +> To add a subgraph to this list, feel free to open an [issue](https://github.com/apollographql/apollo-federation-subgraph-compatibility/issues) or check out the [Apollo Federation Subgraph Maintainers Implementation Guide](https://github.com/apollographql/apollo-federation-subgraph-compatibility/blob/main/CONTRIBUTORS.md) to learn how to submit a PR for your implementation! + +## Table Legend + +| Icon | Description | +| --- | --- | +| Maintained by Apollo | Maintained by Apollo | +| 🟒 | Functionality is supported | +| ❌ | Critical functionality is NOT supported | +| πŸ”² | Additional federation functionality is NOT supported | + +## Ballerina + + + + + + + + + + + + + + + + + + + +
LibraryFederation 1 SupportFederation 2 Support
+ Ballerina GraphQL Module +
+ A spec-compliant, production-ready, Standard Library module for building and interacting with GraphQL APIs using Ballerina.

+ Github: ballerina-platform/module-ballerina-graphql

+ Type: Code first
+ Stars: 144 ⭐
+ Last Release: 2024-05-03

+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requiresπŸ”²
@providesπŸ”²
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareableπŸ”²
@tagπŸ”²
@overrideπŸ”²
@inaccessibleπŸ”²
@composeDirectiveπŸ”²
@interfaceObjectπŸ”²
+
+ +## C# / .NET + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LibraryFederation 1 SupportFederation 2 Support
+ GraphQL for .NET +
+ GraphQL for .NET

+ Github: graphql-dotnet/graphql-dotnet

+ Type: Code first | SDL first
+ Stars: 5.8k ⭐
+ Last Release: 2024-02-06

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

+ Github: ChilliCream/graphql-platform

+ Type: Code first | SDL first
+ Stars: 4.9k ⭐
+ Last Release: 2024-04-22

+ Federation Library: apollographql/federation-hotchocolate + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
+ + +## Elixir + + + + + + + + + + + + + + + + + + + +
LibraryFederation 1 SupportFederation 2 Support
Absinthe
+ The GraphQL toolkit for Elixir
+
+Github: absinthe-graphql/absinthe
+
+Type: Code first
+Stars: 4.2k ⭐
+Last Release: 2021-09-28
+
+Federation Library: DivvyPayHQ/absinthe_federation + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
+ +## Go + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LibraryFederation 1 SupportFederation 2 Support
gqlgen
+ go generate based graphql server library
+
+Github: 99designs/gqlgen
+
+Type: SDL first
+Stars: 9.6k ⭐
+Last Release: 2024-03-11
+
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
GraphQL Go (fork)
+ This is a fork of graphql-go/graphql that adds Federation support
+
+Github: dariuszkuc/graphql
+
+Type: Code first
+Stars: 2 ⭐
+Last Release: 2022-11-11
+
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirectiveπŸ”²
@interfaceObjectπŸ”²
+
+ +## Java / Kotlin + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LibraryFederation 1 SupportFederation 2 Support
dgs-framework
+ GraphQL for Java with Spring Boot made easy.
+
+Github: netflix/dgs-framework
+
+Type: SDL first
+Stars: 3.0k ⭐
+Last Release: 2024-04-30
+
+Core Library: GraphQL Java
+Federation Library: apollographql/federation-jvm  Maintained by Apollo + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
GraphQL Java Kickstart (Spring Boot)
+ GraphQL and GraphiQL Spring Framework Boot Starters - Forked from oembedler/graphql-spring-boot due to inactivity.
+
+Github: graphql-java-kickstart/graphql-spring-boot
+
+Type: SDL first
+Stars: 1.5k ⭐
+Last Release: 2023-12-07
+
+Core Library: GraphQL Java
+Federation Library: apollographql/federation-jvm  Maintained by Apollo + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link❌
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirectiveπŸ”²
@interfaceObjectπŸ”²
+
GraphQL Kotlin
+ Libraries for running GraphQL in Kotlin
+
+Github: ExpediaGroup/graphql-kotlin
+
+Type: Code first
+Stars: 1.7k ⭐
+Last Release: 2024-04-18
+
+Core Library: GraphQL Java
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
Spring GraphQL
+ Spring Integration for GraphQL
+
+Github: spring-projects/spring-graphql
+
+Type: SDL first
+Stars: 1.5k ⭐
+Last Release: 2024-04-16
+
+Core Library: GraphQL Java
+Federation Library: apollographql/federation-jvm  Maintained by Apollo + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
+ +## JavaScript / TypeScript + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LibraryFederation 1 SupportFederation 2 Support
Apollo Server
+ 🌍  Spec-compliant and production ready JavaScript GraphQL server that lets you develop in a schema-first way. Built for Express, Connect, Hapi, Koa, and more.
+
+Github: apollographql/apollo-server  Maintained by Apollo
+
+Type: SDL first
+Stars: 13.7k ⭐
+Last Release: 2024-04-18
+
+Core Library: GraphQL.js
+Federation Library: Apollo Subgraph  Maintained by Apollo + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
express-graphql
+ Create a GraphQL HTTP server with Express.
+
+Github: graphql/express-graphql
+
+Type: SDL first
+Stars: 6.3k ⭐
+Last Release: 2020-11-19
+
+Core Library: GraphQL.js
+Federation Library: Apollo Subgraph  Maintained by Apollo + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirectiveπŸ”²
@interfaceObjectπŸ”²
+
GraphQL Yoga
+ The fully-featured GraphQL server with focus on easy setup, performance and great developer experience.
+
+Github: dotansimha/graphql-yoga
+
+Type: SDL first
+Stars: 8.0k ⭐
+Last Release: 2024-03-29
+
+Core Library: GraphQL.js
+Federation Library: Apollo Subgraph  Maintained by Apollo + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
GraphQL Helix
+ A highly evolved and framework-agnostic GraphQL HTTP server.
+
+Github: contra/graphql-helix
+
+Type: SDL first
+Stars: 831 ⭐
+Last Release: 2022-07-09
+
+Core Library: GraphQL.js
+Federation Library: Apollo Subgraph  Maintained by Apollo + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
Mercurius
+ Implement GraphQL servers and gateways with Fastify
+
+Github: mercurius-js/mercurius
+
+Type: SDL first
+Stars: 2.3k ⭐
+Last Release: 2024-04-22
+
+Core Library: GraphQL.js
+Federation Library: Apollo Subgraph  Maintained by Apollo + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirectiveπŸ”²
@interfaceObjectπŸ”²
+
NestJS (code first)
+ A progressive Node.js framework for building efficient, reliable and scalable server-side applications.
+
+Github: nestjs/graphql
+
+Type: Code first
+Stars: 1.4k ⭐
+Last Release: 2024-02-07
+
+Core Library: GraphQL.js
+Federation Library: Apollo Subgraph  Maintained by Apollo + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@providesπŸ”²
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirectiveπŸ”²
@interfaceObject🟒
+
NestJS (SDL First)
+ A progressive Node.js framework for building efficient, reliable and scalable server-side applications.
+
+Github: nestjs/graphql
+
+Type: SDL first
+Stars: 1.4k ⭐
+Last Release: 2024-02-07
+
+Core Library: GraphQL.js
+Federation Library: Apollo Subgraph  Maintained by Apollo + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
Pothos GraphQL
+ Plugin based GraphQL schema builder that makes building graphql schemas with TypeScript easy, fast and enjoyable.
+
+Github: hayes/pothos
+
+Type: Code first
+Stars: 2.2k ⭐
+Last Release: 2024-04-17
+
+Core Library: GraphQL.js
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
+ +## PHP + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LibraryFederation 1 SupportFederation 2 Support
Lighthouse (Laravel)
+ A framework for serving GraphQL from Laravel
+
+Github: nuwave/lighthouse
+
+Type: SDL first
+Stars: 3.3k ⭐
+Last Release: 2024-05-01
+
+Core Library: webonyx/graphql-php
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
GraphQL PHP
+ PHP implementation of the GraphQL specification based on the reference implementation in JavaScript
+
+Github: webonyx/graphql-php
+
+Type: Code first
+Stars: 4.6k ⭐
+Last Release: 2024-03-11
+
+Federation Library: Skillshare/apollo-federation-php + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link❌
@shareableπŸ”²
@tagπŸ”²
@overrideπŸ”²
@inaccessibleπŸ”²
@composeDirectiveπŸ”²
@interfaceObjectπŸ”²
+
+ +## Python + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LibraryFederation 1 SupportFederation 2 Support
Ariadne
+ Python library for implementing GraphQL servers using schema-first approach.
+
+Github: mirumee/ariadne
+
+Type: SDL first
+Stars: 2.1k ⭐
+Last Release: 2024-03-18
+
+Core Library: GraphQL-core 3
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirectiveπŸ”²
@interfaceObject🟒
+
Graphene
+ GraphQL framework for Python
+
+Github: graphql-python/graphene
+
+Type: Code first
+Stars: 8.0k ⭐
+Last Release: 2023-07-26
+
+Core Library: GraphQL-core 3
+Federation Library: graphql-python/graphene-federation + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirectiveπŸ”²
@interfaceObjectπŸ”²
+
Strawberry
+ A GraphQL library for Python that leverages type annotations πŸ“
+
+Github: strawberry-graphql/strawberry
+
+Type: Code first
+Stars: 3.8k ⭐
+Last Release: 2024-05-01
+
+Core Library: GraphQL-core 3
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
+ +## Ruby + + + + + + + + + + + + + + + + + + + +
LibraryFederation 1 SupportFederation 2 Support
GraphQL Ruby
+ Ruby implementation of GraphQL
+
+Github: rmosolgo/graphql-ruby
+
+Type: Code first
+Stars: 5.3k ⭐
+Last Release: 2021-02-12
+
+Federation Library: Gusto/apollo-federation-ruby + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirectiveπŸ”²
@interfaceObject🟒
+
+ +## Rust + + + + + + + + + + + + + + + + + + + +
LibraryFederation 1 SupportFederation 2 Support
async-graphql
+ A GraphQL server library implemented in Rust
+
+Github: async-graphql/async-graphql
+
+Type: Code first
+Stars: 3.2k ⭐
+Last Release: 2022-11-28
+
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObjectπŸ”²
+
+ +## Scala + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LibraryFederation 1 SupportFederation 2 Support
Caliban
+ Functional GraphQL library for Scala
+
+Github: ghostdogpr/caliban
+
+Type: Code first
+Stars: 939 ⭐
+Last Release: 2024-04-16
+
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
Sangria
+ Scala GraphQL implementation
+
+Github: sangria-graphql/sangria
+
+Type: Code first
+Stars: 2.0k ⭐
+Last Release: 2024-02-01
+
+Federation Library: sangria-graphql/sangria-federated + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
+ +## Swift + + + + + + + + + + + + + + + + + + + +
LibraryFederation 1 SupportFederation 2 Support
Graphiti
+ The Swift GraphQL Schema framework for macOS and Linux
+
+Github: GraphQLSwift/Graphiti
+
+Type: SDL first
+Stars: 523 ⭐
+Last Release: 2023-11-15
+
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
+ +## Other Solutions + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LibraryFederation 1 SupportFederation 2 Support
AWS AppSync
+ Serverless GraphQL and Pub/Sub APIs
+
+
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirectiveπŸ”²
@interfaceObjectπŸ”²
+
Dgraph
+ Dgraph is the native GraphQL database with a graph backend. It is open-source, scalable, distributed, highly available and lightning fast.
+
+
+ 		+ + + + + + + + + + + +
_service❌
@key (single)🟒
@key (multi)πŸ”²
@key (composite)πŸ”²
repeatable @keyπŸ”²
@requiresπŸ”²
@providesπŸ”²
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link❌
@shareableπŸ”²
@tagπŸ”²
@overrideπŸ”²
@inaccessibleπŸ”²
@composeDirectiveπŸ”²
@interfaceObjectπŸ”²
+
Grafbase
+ The GraphQL platform
+
+Github: grafbase/grafbase
+
+Type: Code first | SDL first
+Stars: 934 ⭐
+Last Release: 2024-02-23
+
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link❌
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirectiveπŸ”²
@interfaceObjectπŸ”²
+
GraphQL Mesh
+ Executable GraphQL schema from multiple data sources, query anything, run anywhere.
+
+Github: Urigo/graphql-mesh
+
+ +Stars: 3.2k ⭐
+Last Release: 2024-04-30
+
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirectiveπŸ”²
@interfaceObjectπŸ”²
+
Neo4J Graph Database
+ A GraphQL to Cypher query execution layer for Neo4j and JavaScript GraphQL implementations.
+
+Github: neo4j/graphql
+
+Type: Code first | SDL first
+Stars: 485 ⭐
+Last Release: 2024-04-30
+
+Core Library: GraphQL.js
+Federation Library: Apollo Subgraph  Maintained by Apollo + 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)🟒
repeatable @key🟒
@requires🟒
@provides🟒
federated tracing🟒
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirective🟒
@interfaceObject🟒
+
StepZen, an IBM Company
+ Build GraphQL APIs for all your data in a declarative way. Federate across any data source, including GraphQL.
+
+
+ 		+ + + + + + + + + + + +
_service🟒
@key (single)🟒
@key (multi)🟒
@key (composite)πŸ”²
repeatable @keyπŸ”²
@requires🟒
@providesπŸ”²
federated tracingπŸ”²
+ 		+ + + + + + + + + + +
@link🟒
@shareable🟒
@tag🟒
@override🟒
@inaccessible🟒
@composeDirectiveπŸ”²
@interfaceObjectπŸ”²
+
diff --git a/docs/source/building-supergraphs/router.mdx b/docs/source/building-supergraphs/router.mdx deleted file mode 100644 index 28cca4634..000000000 --- a/docs/source/building-supergraphs/router.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -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: - -```mermaid -graph LR; - clients(Clients); - subgraph "Supergraph"; - gateway([Router]); - serviceA[Users
subgraph]; - serviceB[Products
subgraph]; - gateway --- serviceA & serviceB; - end; - clients -.- gateway; - class clients secondary; -``` - -## Choosing a router library - -Apollo actively supports the following options for your router: - -- **The graphos 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 GraphOS Router instances. [See the Federation Quickstart](../quickstart/]) 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). - - - -Apollo recommends starting with the GraphOS Router. It's faster to configure, performant even under high request loads, and supports many enterprise features. - - - -If you'll use the GraphOS Router, get started with the resources linked above. If you'll use Apollo Server, see [Setting up Apollo Gateway](/apollo-server/using-federation/apollo-gateway-setup). diff --git a/docs/source/building-supergraphs/subgraph-specific-fields.mdx b/docs/source/building-supergraphs/subgraph-specific-fields.mdx new file mode 100644 index 000000000..d75fc1c80 --- /dev/null +++ b/docs/source/building-supergraphs/subgraph-specific-fields.mdx @@ -0,0 +1,84 @@ +--- +title: Subgraph Specific Fields +subtitle: Learn fields automatically added to subgraph schemas +description: Subgraph-compatible server libraries automatically add some federation-specific definitions to your subgraph schema such as Query._service and Query._entities. +--- + +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._entities` + + + +[Learn about entities](/graphos/get-started/guides/federate-schemas#entity-overview) 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](/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](/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. + + +## `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`. diff --git a/docs/source/building-supergraphs/subgraphs-overview.mdx b/docs/source/building-supergraphs/subgraphs-overview.mdx deleted file mode 100644 index cc2fd687d..000000000 --- a/docs/source/building-supergraphs/subgraphs-overview.mdx +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Subgraphs -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. - -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.](./compatible-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](/apollo-server/using-federation/apollo-subgraph-setup/). - - - -## 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. - -For more information on securing your subgraphs with a GraphOS cloud supergraph, see [this article](/graphos/graphs/securing-a-subgraph). - -### 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 (this policy is appropriate for many monolithic public API servers, but not for 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._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](/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](/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. - - -### `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`. diff --git a/docs/source/entities/contribute-fields.mdx b/docs/source/entities/contribute-fields.mdx index 6bc8bec9b..83e81df83 100644 --- a/docs/source/entities/contribute-fields.mdx +++ b/docs/source/entities/contribute-fields.mdx @@ -33,9 +33,9 @@ type Product @key(fields: "id") { By default, each subgraph must contribute different fields, with the important exception of `@key` fields. If multiple subgraphs attempt to contribute the same field, a composition error occurs. -To override this default behavior, see [Resolving another subgraph's field](./resolving-another-subgraphs-field). +To override this default behavior, see [Resolving another subgraph's field](/graphos/schema-design/federated-schemas/entities/resolve-another-subgraphs-fields). -Each subgraph that contributes fields to an entity must [define a reference resolver](./#2-define-a-reference-resolver) for that entity. +Each subgraph that contributes fields to an entity must [define a reference resolver](/graphos/get-started/guides/federate-schemas/#2-define-a-reference-resolver) for that entity. ## Contributing computed entity fields diff --git a/docs/source/entities/define-advanced-keys.mdx b/docs/source/entities/define-advanced-keys.mdx index edee345e6..c3216d514 100644 --- a/docs/source/entities/define-advanced-keys.mdx +++ b/docs/source/entities/define-advanced-keys.mdx @@ -71,7 +71,7 @@ That means either `id` or (`id` and `sku`) is enough to uniquely identify the en ### Referencing entities with multiple keys -A subgraph that [references an entity without contributing any fields](./entities/#referencing-an-entity-without-contributing-fields) can use any `@key` fields in its stub definition. For example, if the Products subgraph defines the `Product` entity like this: +A subgraph that [references an entity without contributing any fields](/graphos/schema-design/federated-schemas/entities/contribute-fields#referencing-an-entity-without-contributing-fields) can use any `@key` fields in its stub definition. For example, if the Products subgraph defines the `Product` entity like this: ```graphql {1} title="Products subgraph" type Product @key(fields: "id") @key(fields: "sku") { @@ -242,4 +242,4 @@ type Query { ## Next steps -If you haven't already, learn how to [contribute entity fields](./contribute-fields) to the supergraph and [reference them](./contribute-fields#referencing-an-entity-without-contributing-fields) from subgraphs that don't contribute any fields. +If you haven't already, learn how to [contribute entity fields](/graphos/schema-design/federated-schemas/entities/contribute-fields) to the supergraph and [reference them](/graphos/schema-design/federated-schemas/entities/contribute-fields#referencing-an-entity-without-contributing-fields) from subgraphs that don't contribute any fields. diff --git a/docs/source/entities/handling-n-plus-one.mdx b/docs/source/entities/handling-n-plus-one.mdx index 1d9ed1816..091d22146 100644 --- a/docs/source/entities/handling-n-plus-one.mdx +++ b/docs/source/entities/handling-n-plus-one.mdx @@ -162,8 +162,8 @@ QueryPlan { -Most subgraph implementations (including [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph/)) don't write the [`Query._entities` resolver](./building-supergraphs/subgraphs-overview/#query_entities) directly. -Instead, they use the [reference resolver API](./#2-define-a-reference-resolver) for resolving an individual entity reference: +Most subgraph implementations (including [`@apollo/subgraph`](/apollo-server/using-federation/api/apollo-subgraph/)) don't write the [`Query._entities` resolver](/graphos/reference/federation/subgraph-specific-fields/#query_entities) directly. +Instead, they use the [reference resolver API](/graphos/get-started/guides/federate-schemas/#2-define-a-reference-resolver) for resolving an individual entity reference: ```js const resolvers = { diff --git a/docs/source/entities/index.mdx b/docs/source/entities/index.mdx deleted file mode 100644 index 221de3b17..000000000 --- a/docs/source/entities/index.mdx +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Entities in Apollo Federation -subtitle: Learn how to define federated types across multiple subgraphs -description: Learn to define and contribute to object types that resolve their fields across multiple services in a federated GraphQL architecture. ---- - - - -_Entities_ are a fundamental building block of Apollo Federation. -In a supergraph, an entity is an object type that can resolve its fields across multiple subgraphs. -Each subgraph can contribute different fields to the entity and is responsible for resolving only the fields that it contributes. -This enables subgraphs to adhere to the separation of concerns principle. - -For example, this `Product` entity's fields are defined and resolved across two subgraphs: - - - -```graphql title="Products subgraph" -type Product @key(fields: "id") { - id: ID! - name: String! - price: Int -} -``` - -```graphql title="Inventory subgraph" -type Product @key(fields: "id") { - id: ID! - inStock: Boolean! -} -``` - - - - - -Only object types can be entities. - - - -This guide goes over how to define entities in your subgraph schemas and code. - -## Defining an entity - -To define an entity within a particular subgraph, you do the following: - -1. Apply the [`@key` directive](#1-define-a-key) to an object type. -2. Define the object type's [reference resolver](#2-define-a-reference-resolver). - -### 1. Define a `@key` - -In a subgraph schema, you can designate any object type as an entity by adding the `@key` directive to its definition, like so: - -```graphql {1} title="Products subgraph" -type Product @key(fields: "id") { - id: ID! - name: String! - price: Int -} -``` - -The `@key` directive defines an entity's _unique key_, which consists of one or more of the type's `fields`. -In the previous example, the `Product` entity's unique key is its `id` field. -Every instance of an entity must be uniquely identifiable by its `@key` field(s). -Key fields' uniqueness enable your router to associate fields from different subgraphs with the same entity instance. - -In most cases, the `@key` field(s) for the same entity will be the same across subgraphs. -For example, if one subgraph uses `id` as the `@key` field for the `Product` entity, other subgraphs should likely do the same. -However, this [isn't strictly required](./define-advanced-keys#differing-keys-across-subgraphs). - -If coming from a database context, it can be helpful to think of a `@key` as an entity's [primary key](https://en.wikipedia.org/wiki/Primary_key). -This term isn't completely accurate for entities since a single entity can have [multiple `@key`s](./define-advanced-keys#multiple-keys). The field(s) you select for an entity's `@key` must, however, uniquely identify the entity. -In that way, `@key`s are similar to [candidate keys](https://en.wikipedia.org/wiki/Candidate_key). - - - -```graphql title="Products subgraph" -type Product @key(fields: "id") { - id: ID! - name: String! - price: Int -} -``` - -```graphql title="Inventory subgraph" -type Product @key(fields: "id") { - id: ID! - inStock: Boolean! -} -``` - - - -For more information on advanced key options, like defining [multiple keys](./define-advanced-keys/#multiple-keys) or [compound keys](./define-advanced-keys/#compound-keys), see the guide on [Defining keys](./define-advanced-keys). - -#### Key field limitations - -An entity's `@key` cannot include: - -- Fields that return a union or interface -- Fields that take arguments - -Though not strictly required, it's best to use non-nullable fields for keys. If you use fields that return `null` values, GraphOS may encounter issues resolving the entity. - -### 2. Define a reference resolver - -The `@key` directive effectively tells the router, "This subgraph can resolve an instance of this entity if you provide its unique key." For this to be true, the subgraph must 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](../building-supergraphs/compatible-subgraphs/), see its documentation for creating reference resolvers or the equivalent functionality. - - - -For the `Product` entity defined [above](#1-define-a-key), the reference resolver might look like this: - -```js {4-6} title="resolvers.js" -// Products subgraph -const resolvers = { - Product: { - __resolveReference(productRepresentation) { - return fetchProductByID(productRepresentation.id); - } - }, - // ...other resolvers... -} -``` - -Let's break this example down: - -- You declare an entity's reference resolver in your resolver map, as a member of the entity's corresponding object. -- A reference resolver's name is always `__resolveReference`. -- A reference resolver's first parameter is a representation of the entity being resolved. - - An entity representation is an object that contains the entity's `@key` fields, plus its `__typename` field. These values are automatically provided to your subgraph by your router. -- A reference resolver is responsible for returning all of the entity fields that this subgraph defines. - - In this example, the hypothetical `fetchProductByID` function fetches a particular `Product`'s field data based on its `id`. - - - -A particular reference resolver might be called many times to resolve a single query. It's crucial that reference resolvers account for "N+1" issues (typically via [data loaders](https://github.com/graphql/dataloader)). For details, see [Handling the N+1 problem](./handling-n-plus-one). - - - -Every subgraph that contributes at least one unique field to an entity must define a reference resolver for that entity. - -To learn more about `__resolveReference` in Apollo Server, see the [API docs](/apollo-server/using-federation/api/apollo-subgraph/#__resolvereference). - -## Next steps - -Once you [publish your updated subgraph schemas](../quickstart#step-3-publish-your-subgraphs), GraphOS composes them into a supergraph schema. -Clients querying your supergraph can interact with entity fields without needing to know the details of which subgraphs contribute which fields. - -To learn about more advanced ways of using entities, check out these guides: - -- [Define Advanced Keys](./define-advanced-keys), including compound and nested key fields -- [Contribute and Reference Entity Fields](./contribute-fields), including computed fields diff --git a/docs/source/entities/interfaces.mdx b/docs/source/entities/interfaces.mdx index cac12cd0b..9700685bd 100644 --- a/docs/source/entities/interfaces.mdx +++ b/docs/source/entities/interfaces.mdx @@ -5,7 +5,7 @@ description: Discover how to efficiently add polymorphic fields to GraphQL inter minVersion: 2.3 --- -Apollo Federation provides powerful extensions to GraphQL interfaces, specifically for use with your supergraph's [entities](../entities/): +Apollo Federation provides powerful extensions to GraphQL interfaces, specifically for use with your supergraph's [entities](/graphos/get-started/guides/federate-schemas#entity-overview): 1. Apply the `@key` directive to an `interface` definition to make it an _entity interface_. 2. In other subgraphs, use the `@interfaceObject` directive to automatically add fields to every entity that implements your entity interface. @@ -64,7 +64,7 @@ This example is short, but there's a lot to it. Let's break it down: - Subgraph B defines the new `Media.reviews` field. - Subgraph B will also be responsible for resolving the `reviews` field. To learn how, see [Resolving an `@interfaceObject`](#resolving-an-interfaceobject). -When [composition](./composition/) runs for the above subgraph schemas, it identifies Subgraph B's `@interfaceObject`. It adds the new `reviews` field to the supergraph schema's `Media` interface, and it also adds that field to the implementing `Book` entity (along with any others): +When composition runs for the above subgraph schemas, it identifies Subgraph B's `@interfaceObject`. It adds the new `reviews` field to the supergraph schema's `Media` interface, and it also adds that field to the implementing `Book` entity (along with any others): ```graphql title="Supergraph schema (simplified)" interface Media @key(fields: "id") { @@ -84,7 +84,7 @@ type Review { } ``` -Subgraph B could have added `Book.reviews` by [contributing the field](../entities#contributing-entity-fields) directly to the entity as usual. However, what if we wanted to add `reviews` to a hundred different entity implementations of `Media`? +Subgraph B could have added `Book.reviews` by [contributing the field](/graphos/schema-design/federated-schemas/entities/contribute-fields) directly to the entity as usual. However, what if we wanted to add `reviews` to a hundred different entity implementations of `Media`? By instead adding entity fields via `@interfaceObject`, we can avoid redefining a hundred entities in Subgraph B (not to mention adding more definitions whenever a new implementing entity is created). [Learn more.](#why-is-interfaceobject-necessary) @@ -94,7 +94,7 @@ To use entity interfaces and `@interfaceObject`, your supergraph must adhere to ### Enabling support -- If they don't already, all of your subgraph schemas must use the [`@link` directive](./federated-directives/#importing-directives) to enable Federation 2 features. +- If they don't already, all of your subgraph schemas must use the [`@link` directive](/graphos/reference/federation/directives/#importing-directives) to enable Federation 2 features. - Any subgraph schema that uses the `@interfaceObject` directive or applies `@key` to an `interface` must target v2.3 or later of the Apollo Federation specfication: ```graphql @@ -107,7 +107,7 @@ To use entity interfaces and `@interfaceObject`, your supergraph must adhere to ) ``` - Additionally, schemas that use `@interfaceObject` must include it in the [`@link` directive's](./federated-directives/#importing-directives) `import` array as shown above. + Additionally, schemas that use `@interfaceObject` must include it in the [`@link` directive's](/graphos/reference/federation/directives/#importing-directives) `import` array as shown above. ### Usage rules @@ -183,11 +183,11 @@ interface Media @key(fields: "id") { } ``` -As it does with any [standard entity](../entities/#1-define-a-key), `@key` indicates "this subgraph can resolve any instance of this type if provided its `@key` fields." This means Subgraph A needs to define a reference resolver for `Media`, just as it would for any other entity. +As it does with any [standard entity](/graphos/get-started/guides/federate-schemas/#1-define-a-key), `@key` indicates "this subgraph can resolve any instance of this type if provided its `@key` fields." This means Subgraph A needs to define a reference resolver for `Media`, just as it would for any other entity. -The method for defining a reference resolver depends on which [subgraph library](../building-supergraphs/compatible-subgraphs/) you use. Some subgraph libraries might use a different term for this functionality. Consult your library's documentation for details. +The method for defining a reference resolver depends on which [subgraph library](/graphos/reference/federation/compatible-subgraphs) you use. Some subgraph libraries might use a different term for this functionality. Consult your library's documentation for details. diff --git a/docs/source/entities/migrate-fields.mdx b/docs/source/entities/migrate-fields.mdx index f4668010a..849be1547 100644 --- a/docs/source/entities/migrate-fields.mdx +++ b/docs/source/entities/migrate-fields.mdx @@ -84,7 +84,7 @@ type Bill @key(fields: "id") { ``` - Applying the `@override` directive tells the router to resolve the `amount` field in the Billing subgraph instead of the Payments subgraph. -3. Publish the Billing subgraph's updated schema to GraphOS with [`rover subgraph publish`](/graphos/delivery/#subgraph-schemas). +3. Publish the Billing subgraph's updated schema to GraphOS with [`rover subgraph publish`](/graphos/platform/schema-management/delivery/publish/#subgraph-schemas). When the router receives its updated supergraph schema, it immediately starts resolving the `Bill.amount` field from the Billing subgraph while continuing to resolve `Bill.payment` from the Payments subgraph. @@ -189,7 +189,7 @@ type Bill @key(fields: "id") { - Adding a `label` argument to the `@override` directive sets the percentage of traffic to direct to the Billing subgraph. Start with a small percentage. Setting `label: "percent(1)"` means that 1 percent of the requests for `amount` are resolved by the Billing subgraph, while the remaining 99 percent are resolved by the Payments subgraph. -3. Publish the Billing subgraph's updated schema to GraphOS with [`rover subgraph publish`](/graphos/delivery/#subgraph-schemas). +3. Publish the Billing subgraph's updated schema to GraphOS with [`rover subgraph publish`](/graphos/platform/schema-management/delivery/publish/#subgraph-schemas). When the router receives its updated supergraph schema, it starts resolving the `Bill.amount` field from the Billing subgraph approximately 1% of the time, while continuing to resolve it from the Payments subgraph the other 99%. @@ -293,7 +293,7 @@ The router provides an interface for coprocessors and rhai scripts to resolve ar This lets you dial up or disable a label's rollout status without requiring a subgraph publish. A coprocessor or Rhai script that implements this should take the following steps: -1. Implement the [`SupergraphService`](/router/customizations/rhai/#supergraphservice) +1. Implement the [`SupergraphService`](/graphos/routing/customization/rhai/#supergraphservice) 2. Inspect the `apollo_override::unresolved_labels` context key to determine which labels exist in the schema that haven't been resolved by the router. 3. Resolve the labels using your feature flag service (or any other mechanism). 4. Add the resolved labels to the `apollo_override::labels_to_override` context key. @@ -322,7 +322,7 @@ For most use cases, Apollo recommends using the [`@override` method above](#incr Using `@override` to migrate entity fields enables us to migrate fields incrementally with zero downtime. However, doing so requires three separate schema publishes. -If you're using [manual composition](./federated-schemas/composition#manually-with-the-rover-cli), each schema change requires redeploying your router. +If you're using [manual composition](/graphos/schema-design/federated-schemas/composition#manually-with-the-rover-cli), each schema change requires redeploying your router. With careful coordination, you can perform the same migration with only a single router redeploy. 1. In the Billing subgraph, define the `Bill` entity, along with its corresponding resolvers. These new resolvers should behave identically to the Payment subgraph resolvers they're replacing. diff --git a/docs/source/entities/use-contexts.mdx b/docs/source/entities/use-contexts.mdx index e782e4b53..9cd8407dc 100644 --- a/docs/source/entities/use-contexts.mdx +++ b/docs/source/entities/use-contexts.mdx @@ -7,7 +7,7 @@ minVersion: 2.8 -The `@context` and `@fromContext` directives are [Enterprise features](/router/enterprise-features) of the Apollo Router and require an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). If your organization doesn't have an Enterprise plan, you can test it out by signing up for a free [Enterprise trial](/graphos/org/plans/#enterprise-trials). +The `@context` and `@fromContext` directives are [Enterprise features](https://www.apollographql.com/pricing) of the Apollo Router and require an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). If your organization doesn't have an Enterprise plan, you can test it out by signing up for a free [Enterprise trial](https://studio.apollographql.com/signup?referrer=docs). diff --git a/docs/source/errors.mdx b/docs/source/errors.mdx index 390047304..7f2f90ceb 100644 --- a/docs/source/errors.mdx +++ b/docs/source/errors.mdx @@ -5,7 +5,7 @@ description: Reference the error codes encountered during Apollo Federation sche toc: false --- -When GraphOS attempts to compose the schemas provided by your [subgraphs](./building-supergraphs/subgraphs-overview/) into a supergraph schema, it confirms that: +When GraphOS attempts to compose your subgraph schemas into a supergraph schema, it confirms that: - The subgraphs have valid GraphQL and Federation syntax - The resulting supergraph schema is valid diff --git a/docs/source/federated-schemas/composition.mdx b/docs/source/federated-schemas/composition.mdx deleted file mode 100644 index 80cb5ea16..000000000 --- a/docs/source/federated-schemas/composition.mdx +++ /dev/null @@ -1,561 +0,0 @@ ---- -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): - -```mermaid -graph TB; - serviceA[Subgraph
schema
A]; - serviceB[Subgraph
schema
B]; - serviceC[Subgraph
schema
C]; - composition[["πŸ› 
Composition "]]; - supergraph{{"Supergraph schema
(A + B + C + routing machinery)"}}; - serviceA & serviceB & serviceC --> composition; - composition -- "(Composition succeeds)" --> supergraph; - class composition tertiary; -``` - -The supergraph schema includes all of the type and field definitions from your subgraph schemas. It also includes metadata that enables your router to intelligently route incoming GraphQL operations across all of your different subgraphs. - -## Supported methods - -You can perform schema composition with any of the following methods: - -### Automatically with GraphOS - -With [managed federation](../managed-federation/overview/), Apollo GraphOS performs composition automatically whenever one of your subgraphs updates its published schema. This enables your running router to dynamically fetch an updated supergraph schema from Apollo as soon as it's available: - -```mermaid -graph LR; - subgraph "Your infrastructure" - serviceA[Products
subgraph]; - serviceB[Reviews
subgraph]; - gateway([Router]); - end - subgraph "GraphOS" - registry{{Apollo Schema
Registry}}; - uplink{{Apollo
Uplink}} - end - serviceA & serviceB -->|Publishes schema| registry; - registry -->|Updates config| uplink; - gateway -->|Polls for config changes| uplink; - class registry secondary; - class uplink secondary; -``` - -To learn how to perform composition with managed federation, see the [quickstart](../quickstart/studio-composition/). - - - -GraphOS also provides a [schema linter](/graphos/delivery/schema-linter) with [composition specific rules](/graphos/delivery/linter-rules#composition-rules) to help you follow best practices. You can set up schema checks for your graph in GraphOS Studio or perform one-off linting with the Rover CLI. Check out the [schema linting](/graphos/delivery/schema-linter) docs to learn more. - - - -### Manually with the Rover CLI - -The [Rover CLI](https://www.apollographql.com/docs/rover/) supports a `supergraph compose` command that you can use to compose a supergraph schema from a collection of subgraph schemas: - -```bash -rover supergraph compose --config ./supergraph-config.yaml -``` - -To learn how to install Rover and use this command, see the [quickstart](../quickstart/setup/#install-the-rover-cli). - -## Breaking composition - -Sometimes, your subgraph schemas might conflict in a way that causes composition to fail. This is called _breaking composition_. - -For example, take a look at these two subgraph schemas: - -

❌

- - -```graphql {2} title="Subgraph A" -type Event @shareable { - timestamp: String! -} -``` - -```graphql {2} title="Subgraph B" -type Event @shareable { - timestamp: Int! -} -``` - - - -One subgraph defines `Event.timestamp` as a `String`, and the other defines it as an `Int`. Composition doesn't know which type to use, so it fails. - - - -For examples of valid inconsistencies in field return types, see [Differing shared field return types](./sharing-types/#return-types). - - - -Breaking composition is a helpful feature of federation! Whenever a team modifies their subgraph schema, those changes might conflict with another subgraph. But that conflict won't affect your router, because composition fails to generate a new supergraph schema. It's like a compiler error that prevents you from running invalid code. - -## Rules of composition -In Federation 2, your subgraph schemas must follow all of these rules to successfully compose into a supergraph schema: - -- Multiple subgraphs can't define the same field on an object type, unless that field is [shareable](./sharing-types/#using-shareable). -- A shared field must have both a compatible return type and compatible argument types across each defining subgraph. - - For examples of compatible and incompatible differences between subgraphs, see [Differing shared fields](./sharing-types/#differing-shared-fields). -- If multiple subgraphs define the same type, each field of that type must be resolvable by every valid GraphQL operation that includes it. - - This rule is the most complex and the most essential to Federation 2. [Let's look at it more closely.](#unresolvable-field-example) - -### Unresolvable field example - -This example presents a field of a shared type that is not always resolvable (and therefore [breaks composition](#breaking-composition)). - -Consider these subgraph schemas: - -

❌

- - - -```graphql title="Subgraph A" -type Query { - positionA: Position! -} - -type Position @shareable { - x: Int! - y: Int! -} -``` - -```graphql title="Subgraph B" -type Query { - positionB: Position! -} - -type Position @shareable { - x: Int! - y: Int! - z: Int! -} -``` - - - - -Note the following about these two subgraphs: - -- They both define a shared `Position` type. -- They both define a top-level `Query` field that returns a `Position`. -- Subgraph B's `Position` includes a `z` field, whereas Subgraph A's definition only includes shared `x` and `y` fields. - -Individually, these subgraph schemas are perfectly valid. However, if they're combined, they break composition. Why? - -The composition process attempts to merge inconsistent type definitions into a single definition for the supergraph schema. In this case, the resulting definition for `Position` exactly matches Subgraph B's definition: - -

❌

- -```graphql title="Hypothetical supergraph schema" -type Query { - # From A - positionA: Position! - # From B - positionB: Position! -} - -type Position { - # From A+B - x: Int! - y: Int! - # From B - z: Int! -} -``` - -Based on this hypothetical supergraph schema, the following query should be valid: - -```graphql {5} -query GetPosition { - positionA { - x - y - z # ⚠️ Can't be resolved! ⚠️ - } -} -``` - -Here's our problem. Only Subgraph A can resolve `Query.positionA`, because Subgraph B doesn't define the field. But Subgraph A doesn't define `Position.z`! - -If the router sent this query to Subgraph A, it would return an error. And without extra configuration, Subgraph B can't resolve a `z` value for a `Position` in Subgraph A. Therefore, `Position.z` is unresolvable for this query. - -Composition recognizes this potential issue, and it fails. The hypothetical supergraph schema above would never actually be generated. - -`Position.z` is an example of a field that is not always resolvable. So now, how do we make sure that such a field is always resolvable? - -### Solutions for unresolvable fields - -There are multiple solutions for making sure that a field of a shared type is always resolvable. Choose a solution based on your use case: - -#### Define the field in every subgraph that defines the type. - -If every subgraph that defines a type could resolve every field of that type without introducing complexity, a straightforward solution is to define and resolve all fields in all of those subgraphs: - -

βœ…

- - - -```graphql {4} title="Subgraph A" -type Position @shareable { - x: Int! - y: Int! - z: Int -} -``` - -```graphql title="Subgraph B" -type Position @shareable { - x: Int! - y: Int! - z: Int! -} -``` - - - -In this case, if Subgraph A only cares about the `x` and `y` fields, its resolver for `z` can always return `null`. - -This is a useful solution for shared types that encapsulate simple scalar data. - - - -You can use the `@inaccessible` directive to incrementally add a value type field to multiple subgraphs without breaking composition. [Learn more.](./sharing-types/#adding-new-shared-fields) - - - -#### Make the shared type an entity - -

βœ…

- - - -```graphql title="Subgraph A" -type User @key(fields: "id") { - id: ID! - name: String! -} -``` - -```graphql title="Subgraph B" -type User @key(fields: "id") { - id: ID! - age: Int! -} -``` - - - -If you make a shared type an [entity](../entities/), different subgraphs can define any number of different fields for that type, as long as they all define key fields for it. - -This is a useful solution when a type corresponds closely to an entry in a data store that one or more of your subgraphs has access to (e.g., a `Users` database). - -## Merging types from multiple subgraphs - -If a particular GraphQL type is defined differently by different subgraphs, composition uses one of two strategies to merge those definitions: _union_ or _intersection_. - -- **Union**: The supergraph schema includes all parts of all subgraph definitions for the type. -- **Intersection**: The supergraph schema includes only the parts of the type that are present in every subgraph that defines the type. - -The merging strategy that composition uses for a particular type depends on the type, as described below. - -### Object, union, and interface types - -Composition always uses the union strategy to merge object, union, and interface types. - -Consider the following subgraph schemas: - - - -```graphql title="Subgraph A" -type User @key(fields: "id") { - id: ID! - name: String! - email: String! -} - -union Media = Book | Movie - -interface BookDetails { - title: String! - author: String! -} -``` - -```graphql title="Subgraph B" -type User @key(fields: "id") { - id: ID! - age: Int! -} - -union Media = Book | Podcast - -interface BookDetails { - title: String! - numPages: Int -} -``` - - - -When these subgraph schemas are composed, the composition process merges the three corresponding types by union. This results in the following type definitions in the supergraph schema: - -```graphql title="Supergraph schema" -type User { - id: ID! - age: Int! - name: String! - email: String! -} - -union Media = Book | Movie | Podcast - -interface BookDetails { - title: String! - author: String! - numPages: Int -} -``` - -Because composition uses the union strategy for these types, subgraphs can contribute distinct parts and guarantee that those parts will appear in the composed supergraph schema. - - - -If different subgraphs contribute different fields to an interface type, any object types that implement that interface must define all contributed fields from all subgraphs. Otherwise, composition fails. - - - -### Input types and field arguments - -Composition always uses the intersection strategy to merge input types and field arguments. This ensures that the router never passes an argument to a subgraph that doesn't define that argument. - -Consider the following subgraph schemas: - - - -```graphql title="Subgraph A" -input UserInput { - name: String! - age: Int -} - -type Library @shareable { - book(title: String, author: String): Book -} -``` - -```graphql title="Subgraph B" -input UserInput { - name: String! - email: String -} - -type Library @shareable { - book(title: String, section: String): Book -} -``` - - - -These subgraphs define different fields for the `UserInput` input type, and they define different arguments for the `Library.book` field. After composition merges using intersection, the supergraph schema definitions look like this: - -```graphql title="Supergraph schema" -input UserInput { - name: String! -} - -type Library { - book(title: String): Book -} -``` - -As you can see, the supergraph schema includes only the input fields and arguments that both subgraphs define. - - - -If the intersection strategy would omit an input field or argument that is non-nullable, composition fails. This is because at least one subgraph requires that field or argument, and the router can't provide it if it's omitted from the supergraph schema. - -When defining input types and field arguments in multiple subgraphs, make sure that every non-nullable field and argument is consistent in every subgraph. For examples, see [Arguments](sharing-types#arguments). - - - -### Enums - -If an enum definition differs between subgraphs, the [composition strategy](#merging-types-from-multiple-subgraphs) depends on how the enum is used: - -| Scenario | Strategy | -|----------|----------| -| The enum is used as the return type for at least one object or interface field. | [Union](#union) | -| The enum is used as the type for at least one field argument or input type field. | [Intersection](#intersection) | -| Both of the above are true. | All definitions must [match exactly](#exact-match) | - -Examples of these scenarios are provided below. - -#### Enum composition examples - -##### Union - -Consider these subgraph schemas: - - - -```graphql title="Subgraph A" -enum Color { - RED - GREEN - BLUE -} - -type Query { - favoriteColor: Color -} -``` - -```graphql title="Subgraph B" -enum Color { - RED - GREEN - YELLOW -} - -type Query { - currentColor: Color -} -``` - - - -In this case, the `Color` enum is used as the return type of at least one object field. Therefore, composition merges the `Color` enum by union, so that all possible subgraph return values are valid. - -This results in the following type definition in the supergraph schema: - -```graphql title="Supergraph schema" -enum Color { - RED - GREEN - BLUE - YELLOW -} -``` - -##### Intersection - -Consider these subgraph schemas: - - - -```graphql title="Subgraph A" -enum Color { - RED - GREEN - BLUE -} - -type Query { - products(color: Color): [Product] -} -``` - -```graphql title="Subgraph B" -enum Color { - RED - GREEN - YELLOW -} - -type Query { - images(color: Color): [Image] -} -``` - - - -In this case, the `Color` enum is used as the type of at least one field argument (or input type field). Therefore, composition merges the `Color` enum by intersection, so that subgraphs never receive a client-provided enum value that they don't support. - -This results in the following type definition in the supergraph schema: - -```graphql title="Supergraph schema" -# BLUE and YELLOW are removed via intersection -enum Color { - RED - GREEN -} -``` - -##### Exact match - -Consider these subgraph schemas: - -

❌

- - - -```graphql title="Subgraph A" -enum Color { - RED - GREEN - BLUE -} - -type Query { - favoriteColor: Color -} -``` - -```graphql title="Subgraph B" -enum Color { - RED - GREEN - YELLOW -} - -type Query { - images(color: Color): [Image] -} -``` - - - -In this case, the `Color` enum is used as both: - -- The return type of at least one object field -- The type of at least one field argument (or input type field) - -Therefore, the definition of the `Color` enum must match exactly in every subgraph that defines it. An exact match is the only scenario that enables union and intersection to produce the same result. - -The subgraph schemas above do not compose, because their definitions of the `Color` enum differ. - -## Directives - -Composition handles a directive differently depending on whether it's an "executable" directive or a "type system" directive. - -### Executable directives - -Executable directives are intended to be used by clients in their queries. They are applied to one or more of the [executable directive locations](http://spec.graphql.org/June2018/#ExecutableDirectiveLocation). For example, you might have a directive definition of `directive @lowercase on FIELD`, which a client could use in their query like so: - -```graphql -query { - getSomeData { - someField @lowercase - } -} -``` - -An executable directive is composed into the supergraph schema only if all of the following conditions are met: - -- The directive is defined in all subgraphs. -- The directive is defined identically in all subgraphs. -- The directive is not included in any [`@composeDirective`](./federated-directives#composedirective) directives. - -### Type system directives - -Type system directives help define the structure of the schema and are not intended for use by clients. They are applied to one or more of the [type system directive locations](http://spec.graphql.org/June2018/#TypeSystemDirectiveLocation). - -These directives are not composed into the supergraph schema, but they can still provide information to the router via the [`@composeDirective`](./federated-directives#composedirective) directive. diff --git a/docs/source/federated-schemas/federated-directives.mdx b/docs/source/federated-schemas/federated-directives.mdx index 6c750b598..90f4b6eba 100644 --- a/docs/source/federated-schemas/federated-directives.mdx +++ b/docs/source/federated-schemas/federated-directives.mdx @@ -118,8 +118,8 @@ type Product @key(fields: "id") { To learn best practices and advanced use cases for `@key`, refer to the following guides: -- [Introduction to entities](../entities) -- [Define advanced keys](../entities/define-advanced-keys) +- [Introduction to entities](/graphos/get-started/guides/federate-schemas#entity-overview) +- [Define advanced keys](/graphos/schema-design/federated-schemas/entities/define-keys) @@ -135,11 +135,11 @@ 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](../building-supergraphs/compatible-subgraphs/). +To check whether your subgraph library supports repeatable directives, see the `repeatable @key` item in [Federation-compatible subgraph implementations](/graphos/reference/federation/compatible-subgraphs). -In Apollo Federation 2.3 and later, you can also apply `@key` to `interface` definitions to create [entity interfaces](../entities/interfaces/). If you apply `@key` to an `interface` in earlier versions of Federation 2, a composition error occurs. +In Apollo Federation 2.3 and later, you can also apply `@key` to `interface` definitions to create [entity interfaces](/graphos/schema-design/federated-schemas/entities/interfaces/). If you apply `@key` to an `interface` in earlier versions of Federation 2, a composition error occurs. #### Arguments @@ -171,7 +171,7 @@ Examples: * `"username region"` * `"name organization { id }"` -See also [Advanced `@key`s](../../entities/define-advanced-keys). +See also [Advanced `@key`s](/graphos/schema-design/federated-schemas/entities/define-keys). @@ -185,9 +185,9 @@ See also [Advanced `@key`s](../../entities/define-advanced-keys). -If `false`, indicates to the router that this subgraph doesn't define a [reference resolver](../entities/#2-define-a-reference-resolver) for this entity. This means that router query plans can't "jump to" this subgraph to resolve fields that aren't defined in another subgraph. +If `false`, indicates to the router that this subgraph doesn't define a [reference resolver](/graphos/get-started/guides/federate-schemas#2-define-a-reference-resolver) for this entity. This means that router query plans can't "jump to" this subgraph to resolve fields that aren't defined in another subgraph. -Most commonly, you set this to `false` when [referencing an entity without contributing fields](../entities/#referencing-an-entity-without-contributing-fields). +Most commonly, you set this to `false` when [referencing an entity without contributing fields](/graphos/schema-design/federated-schemas/entities/contribute-fields#referencing-an-entity-without-contributing-fields). The default value is `true`. @@ -211,7 +211,7 @@ Indicates that an object definition serves as an abstraction of another subgraph During composition, the fields of every `@interfaceObject` are added both to their corresponding `interface` definition and to all entity types that implement that interface. -[Learn more about entity interfaces.](../entities/interfaces/) +[Learn more about entity interfaces.](/graphos/schema-design/federated-schemas/entities/interfaces/) @@ -255,7 +255,7 @@ directive @shareable repeatable on FIELD_DEFINITION | OBJECT -`@shareable` is only `repeatable` in [v2.2](../federation-versions#v22) and later. +`@shareable` is only `repeatable` in [v2.2](/graphos/reference/federation/versions#v22) and later. @@ -287,7 +287,7 @@ If a Federation 2 supergraph includes a Federation 1 subgraph, all value types i If a field is included in an entity's [`@key` directive](#key), that field is automatically considered `@shareable` and the directive is not required in the corresponding subgraph(s). -See also [Value types in Apollo Federation](./sharing-types/) and [Resolving another subgraph's field](../entities/resolve-another-subgraphs-fields). +See also [Value types in Apollo Federation](/graphos/schema-design/federated-schemas/sharing-types/) and [Resolving another subgraph's field](/graphos/schema-design/federated-schemas/entities/resolve-another-subgraphs-fields). The `@shareable` directive is about indicating when an object field can be resolved by multiple subgraphs. As interface fields are not directly resolved (their implementation is), `@shareable` is not meaningful on an interface field and is not allowed (at least since federation 2.2; earlier versions of federation 2 mistakenly ignored `@shareable` on interface fields). @@ -301,11 +301,11 @@ The `@shareable` directive is about indicating when an object field can be resol directive @inaccessible on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION ``` -Indicates that a definition in the subgraph schema should be omitted from the router's [API schema](./overview/#api-schema), even if that definition is also present in other subgraphs. This means that the field is not exposed to clients at all. +Indicates that a definition in the subgraph schema should be omitted from the router's [API schema](/graphos/schema-design/federated-schemas/schema-types/#api-schema), even if that definition is also present in other subgraphs. This means that the field is not exposed to clients at all. Common use cases for `@inaccessible` include: -- Avoiding composition errors while making staggered updates to a definition that's shared across multiple subgraphs (such as a [value type](./sharing-types/#adding-new-shared-fields)) +- Avoiding composition errors while making staggered updates to a definition that's shared across multiple subgraphs (such as a [value type](/graphos/schema-design/federated-schemas/sharing-types/#adding-new-shared-fields)) - Using a private field as part of an entity's [`@key`](#key) without exposing that field to clients @@ -342,7 +342,7 @@ An `@inaccessible` field or type is not omitted from the supergraph schema, so t If a type is marked `@inaccessible`, all fields that return that type must also be marked `@inaccessible`. Otherwise, a composition error occurs. -For more information, see [Using `@inaccessible`](./sharing-types/#using-inaccessible). +For more information, see [Using `@inaccessible`](/graphos/schema-design/federated-schemas/sharing-types/#using-inaccessible). @@ -356,7 +356,7 @@ directive @override(from: String!) on FIELD_DEFINITION Indicates that an object field is now resolved by this subgraph instead of another subgraph where it's also defined. This enables you to migrate a field from one subgraph to another. -You can apply `@override` to [entity](../entities/) fields and fields of the root operation types (such as `Query` and `Mutation`). +You can apply `@override` to [entity](/graphos/schema-design/federated-schemas/entities/) fields and fields of the root operation types (such as `Query` and `Mutation`). @@ -382,7 +382,7 @@ You can apply `@override` to a [`@shareable`](#shareable) field. If you do, only Only one subgraph can `@override` any given field. If multiple subgraphs attempt to `@override` the same field, a composition error occurs. -For more information, see [Migrating entity and root fields](../entities/migrate-fields). +For more information, see [Migrating entity and root fields](/graphos/schema-design/federated-schemas/entities/migrate-fields). @@ -396,7 +396,7 @@ Rolling out any change to a production subgraph, including field migration, risk The _progressive `@override`_ feature enables the gradual, progressive deployment of a subgraph with an `@override` field. As a subgraph developer, you can customize the percentage of traffic that the overriding and overridden subgraphs each resolve for a field. You apply a label to an `@override` field to set the percentage of traffic for the field that should be resolved by the overriding subgraph, with the remaining percentage resolved by the overridden subgraph. You can then monitor the performance of the subgraphs in Studio, resolve any issues, and iteratively and progressively increase the percentage until all traffic is resolved by the overriding subgraph. -To learn more, see the [Incremental migration with `@override`](../entities/migrate-fields#incremental-migration-with-progressive-override) guide. +To learn more, see the [Incremental migration with `@override`](/graphos/schema-design/federated-schemas/entities/migrate-fields#incremental-migration-with-progressive-override) guide. #### Arguments @@ -439,12 +439,12 @@ To learn more, see the [Incremental migration with `@override`](../entities/migr -This argument is available in Apollo Federation 2.7 and later. It is an [Enterprise feature](/router/enterprise-features) of the GraphOS Router and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). You can test it out by signing up for a free [Enterprise trial](/graphos/org/plans/#enterprise-trials). +This argument is available in Apollo Federation 2.7 and later. It is an [Enterprise feature](https://www.apollographql.com/pricing) of the GraphOS Router and requires an organization with a [GraphOS Enterprise plan](https://www.apollographql.com/pricing/). You can test it out by signing up for a free [Enterprise trial](https://studio.apollographql.com/signup?referrer=docs). **Optional.** A string of arbitrary arguments. Supported in this release: -- `percent()` - The percentage of traffic for the field that's resolved by this subgraph. The remaining percentage is resolved by the other ([from](#from)) subgraph. To learn more, see [Incremental migration with `@override`](../entities/migrate-fields#incremental-migration-with-progressive-override). +- `percent()` - The percentage of traffic for the field that's resolved by this subgraph. The remaining percentage is resolved by the other ([from](#from)) subgraph. To learn more, see [Incremental migration with `@override`](/graphos/schema-design/federated-schemas/entities/migrate-fields#incremental-migration-with-progressive-override). @@ -472,7 +472,7 @@ directive @authenticated on | ENUM ``` -Indicates to composition that the target element is accessible only to the authenticated supergraph users. For more granular access control, see the [`@requiresScopes`](#requiresScopes) directive below. Refer to the [router article](/router/configuration/authorization#authenticated) for additional details. +Indicates to composition that the target element is accessible only to the authenticated supergraph users. For more granular access control, see the [`@requiresScopes`](#requiresScopes) directive below. Refer to the [router article](/graphos/routing/security/authorization#authenticated) for additional details. @@ -491,7 +491,7 @@ directive @requiresScopes(scopes: [[federation__Scope!]!]!) on | ENUM ``` -Indicates to composition that the target element is accessible only to the authenticated supergraph users with the appropriate JWT scopes. Refer to the [router article](/router/configuration/authorization#requiresscopes) for additional details. +Indicates to composition that the target element is accessible only to the authenticated supergraph users with the appropriate JWT scopes. Refer to the [router article](/graphos/routing/security/authorization#requiresscopes) for additional details. #### Arguments @@ -540,7 +540,7 @@ directive @policy(policies: [[federation__Policy!]!]!) on | ENUM ``` -Indicates to composition that the target element is restricted based on authorization policies that are evaluated in a Rhai script or coprocessor. Refer to the [router article](/router/configuration/authorization#policy) for additional details. +Indicates to composition that the target element is restricted based on authorization policies that are evaluated in a Rhai script or coprocessor. Refer to the [router article](/graphos/routing/security/authorization#policy) for additional details. #### Arguments @@ -655,7 +655,7 @@ Otherwise, a composition error occurs. -For more information, see [Using `@provides`](../entities/resolve-another-subgraphs-fields#using-provides). +For more information, see [Using `@provides`](/graphos/schema-design/federated-schemas/entities/resolve-another-subgraphs-fields#using-provides). #### Arguments @@ -722,7 +722,7 @@ If a subgraph `@requires` an entity field, the subgraph must define that field a -See also [Contributing computed entity fields](../entities/contribute-fields#contributing-computed-entity-fields). +See also [Contributing computed entity fields](/graphos/schema-design/federated-schemas/entities/contribute-fields#contributing-computed-entity-fields). #### Arguments @@ -772,7 +772,7 @@ Examples: directive @tag(name: String!) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION | SCHEMA ``` -Applies arbitrary string metadata to a schema location. Custom tooling can use this metadata during any step of the schema delivery flow, including composition, static analysis, and documentation. The GraphOS Enterprise [contracts feature](/graphos/delivery/contracts/) uses `@tag` with its inclusion and exclusion filters. +Applies arbitrary string metadata to a schema location. Custom tooling can use this metadata during any step of the schema delivery flow, including composition, static analysis, and documentation. The GraphOS Enterprise [contracts feature](/graphos/platform/schema-management/delivery/contracts/overview) uses `@tag` with its inclusion and exclusion filters. @@ -850,11 +850,11 @@ type Employee implements User @tag(name: "team-admin") { directive @composeDirective(name: String!) repeatable on SCHEMA ``` -Indicates to composition that all uses of a particular custom [type system directive](./composition#type-system-directives) in the subgraph schema should be preserved in the supergraph schema (by default, composition omits most directives from the supergraph schema). +Indicates to composition that all uses of a particular custom [type system directive](/graphos/reference/federation/composition-rules/#type-system-directives) in the subgraph schema should be preserved in the supergraph schema (by default, composition omits most directives from the supergraph schema). -Do not use this directive with an [executable directive](./composition#executable-directives). Executable directives have different rules for composition. +Do not use this directive with an [executable directive](/graphos/reference/federation/composition-rules/#executable-directives). Executable directives have different rules for composition. @@ -874,7 +874,7 @@ directive @hello on FIELD_DEFINITION This directive has the following requirements: - - Ensure your [subgraph library](../building-supergraphs/compatible-subgraphs) supports `@composeDirective` or try manually adding the `@composeDirective` definition to your subgraph schema. + - Ensure your [subgraph library](/graphos/reference/federation/compatible-subgraphs) supports `@composeDirective` or try manually adding the `@composeDirective` definition to your subgraph schema. - The directive to preserve must be defined and imported from a core specification via the `@link` directive. - The specified directive `name` must match the name used for the directive in this subgraph. - If you use the `as` argument in your `@link` definition to modify the directive's name from its spec's default, provide the modified name, not the default name. @@ -976,12 +976,12 @@ The selection syntax for `@fromContext` used in its `ContextFieldValue` is simil - 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 `ContextFieldValue` must be expressed within the current subgraph. If the fields are referenced across multiple subgraphs, they must be annotated with [`@external`](../entities/use-contexts#referencing-fields-across-subgraphs) . +- All fields referenced in the `ContextFieldValue` must be expressed within the current subgraph. If the fields are referenced across multiple subgraphs, they must be annotated with [`@external`](/graphos/schema-design/federated-schemas/entities/use-contexts#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 `ContextFieldValue` 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/use-contexts). +For examples using `@context` and `@fromContext`, see [Using contexts to share data along type hierarchies](/federation/entities/use-contexts). ## Customizing demand controls diff --git a/docs/source/federated-schemas/index.mdx b/docs/source/federated-schemas/index.mdx deleted file mode 100644 index 91ee1c0c4..000000000 --- a/docs/source/federated-schemas/index.mdx +++ /dev/null @@ -1,232 +0,0 @@ ---- -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: - -```mermaid -graph TB; - serviceA[Subgraph
schema
A]; - serviceB[Subgraph
schema
B]; - serviceC[Subgraph
schema
C]; - composition[["πŸ› 
Composition "]]; - supergraph{{"Supergraph schema
(A + B + C + routing machinery)"}}; - api(["API schema
(A + B + C)"]); - serviceA & serviceB & serviceC --> composition; - composition -- "(Composition succeeds)" --> supergraph; - supergraph -- "(Remove routing machinery)" --> api; - class composition tertiary; -``` - -* **Subgraph schemas.** Each subgraph has a distinct schema that indicates which types and fields of your composed supergraph it can resolve. - * These are the only schemas that your teams define manually. -* **Supergraph schema.** This schema combines all of the types and fields from your subgraph schemas, plus some federation-specific information that tells your router which subgraphs can resolve which fields. - * This schema is the result of performing [composition](./composition/) on your collection of subgraph schemas. -* **API schema.** This schema is similar to the supergraph schema, but it omits federation-specific types, fields, and directives that are considered "machinery" and are not part of your public API. - * This is the schema that your router exposes to clients, which don't need to know internal implementation details about your graph. - -Let's look at an example! - -## Subgraph schemas - -Below are example schemas for three subgraphs in an e-commerce company's supergraph. Each subgraph is implemented as a separate GraphQL API: - - - -```graphql title="Users" -type Query { - me: User -} - -type User @key(fields: "id") { - id: ID! - username: String! @shareable -} - -# (Subgraph schemas include -# this to opt in to -# Federation 2 features.) -extend schema - @link(url: "https://specs.apollo.dev/federation/v2.3", - import: ["@key", "@shareable"]) -``` - -```graphql title="Products" -type Query { - topProducts(first: Int = 5): [Product] -} - -type Product @key(fields: "upc") { - upc: String! - name: String! - price: Int -} - -extend schema - @link(url: "https://specs.apollo.dev/federation/v2.3", - import: ["@key", "@shareable"]) -``` - - - - - -```graphql title="Reviews" -type Review { - body: String - author: User @provides(fields: "username") - product: Product -} - -type User @key(fields: "id") { - id: ID! - username: String! @external - reviews: [Review] -} - -type Product @key(fields: "upc") { - upc: String! - reviews: [Review] -} - -# (This subgraph uses additional -# federated directives) -extend schema - @link(url: "https://specs.apollo.dev/federation/v2.3", - import: ["@key", "@shareable", "@provides", "@external"]) -``` - - - -As these schemas show, multiple subgraphs can contribute unique fields to a single type. For example, the Products subgraph and the Reviews subgraph both contribute fields to the `Product` type. - -## Supergraph schema - -The supergraph schema is the output of [schema composition](./composition/). It serves the following purposes: - -* It provides your router with the name and endpoint URL for each of your subgraphs. -* It includes all types and fields defined by all of your subgraphs. -* It tells your router which of your subgraphs can resolve which GraphQL fields. - -Here's the supergraph schema composed with [the subgraph schemas above](#subgraph-schemas): - - - -```graphql -schema - @link(url: "https://specs.apollo.dev/link/v1.0") - @link(url: "https://specs.apollo.dev/join/v0.3", for: EXECUTION) -{ - query: Query -} - -directive @join__enumValue(graph: join__Graph!) repeatable on ENUM_VALUE - -directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet, type: String, external: Boolean, override: String, usedOverridden: Boolean) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION - -directive @join__graph(name: String!, url: String!) on ENUM_VALUE - -directive @join__implements(graph: join__Graph!, interface: String!) repeatable on OBJECT | INTERFACE - -directive @join__type(graph: join__Graph!, key: join__FieldSet, extension: Boolean! = false, resolvable: Boolean! = true, isInterfaceObject: Boolean! = false) repeatable on OBJECT | INTERFACE | UNION | ENUM | INPUT_OBJECT | SCALAR - -directive @join__unionMember(graph: join__Graph!, member: String!) repeatable on UNION - -directive @link(url: String, as: String, for: link__Purpose, import: [link__Import]) repeatable on SCHEMA - -scalar join__FieldSet - -enum join__Graph { - PRODUCTS @join__graph(name: "products", url: "http://localhost:4002/graphql") - REVIEWS @join__graph(name: "reviews", url: "http://localhost:4003/graphql") - USERS @join__graph(name: "users", url: "http://localhost:4001/graphql") -} - -scalar link__Import - -enum link__Purpose { - """ - `SECURITY` features provide metadata necessary to securely resolve fields. - """ - SECURITY - - """ - `EXECUTION` features provide metadata necessary for operation execution. - """ - EXECUTION -} - -type Product - @join__type(graph: PRODUCTS, key: "upc") - @join__type(graph: REVIEWS, key: "upc") -{ - upc: String! - name: String! @join__field(graph: PRODUCTS) - price: Int @join__field(graph: PRODUCTS) - reviews: [Review] @join__field(graph: REVIEWS) -} - -type Query - @join__type(graph: PRODUCTS) - @join__type(graph: REVIEWS) - @join__type(graph: USERS) -{ - topProducts(first: Int = 5): [Product] @join__field(graph: PRODUCTS) - me: User @join__field(graph: USERS) -} - -type Review - @join__type(graph: REVIEWS) -{ - body: String - author: User @join__field(graph: REVIEWS, provides: "username") - product: Product -} - -type User - @join__type(graph: REVIEWS, key: "id") - @join__type(graph: USERS, key: "id") -{ - id: ID! - username: String! @join__field(graph: REVIEWS, external: true) @join__field(graph: USERS) - reviews: [Review] @join__field(graph: REVIEWS) -} -``` - - - -As you can see, the supergraph schema includes a lot of Federation-specific additions! These additions are used only by the router, and you'll never need to add them manually. - -## API schema - -The router uses its [supergraph schema](#supergraph-schema) to produce an **API schema**, which it exposes to clients as your actual GraphQL API. This schema cleanly and logically represents the combination of your [subgraph schemas](#subgraph-schemas): - -```graphql -type Product { - name: String! - price: Int - reviews: [Review] - upc: String! -} - -type Query { - me: User - topProducts(first: Int = 5): [Product] -} - -type Review { - author: User - body: String - product: Product -} - -type User { - id: ID! - reviews: [Review] - username: String! -} -``` - -Unlike the supergraph schema, this schema hides the fact that your GraphQL API is composed of multiple distinct GraphQL APIs. diff --git a/docs/source/federated-schemas/sharing-types.mdx b/docs/source/federated-schemas/sharing-types.mdx deleted file mode 100644 index ebaf2daf0..000000000 --- a/docs/source/federated-schemas/sharing-types.mdx +++ /dev/null @@ -1,645 +0,0 @@ ---- -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/). - -For example, suppose you want to define and reuse a generic `Position` type in different subgraphs: - -```graphql -type Position { - x: Int! - y: Int! -} -``` - -Types like this are called _value types_. This article describes how to share value types and their fields in federated graph, enabling multiple subgraphs to define and resolve them. - -## Sharing object types - -By default in [Federation 2 subgraphs](../federation-2/moving-to-federation-2/#step-3-update-individual-subgraphs), a single object field can't be defined or resolved by more than one subgraph schema. - -Consider the following `Position` example: - -

❌

- - - -```graphql {2-3} title="Subgraph A" -type Position { - x: Int! - y: Int! -} -``` - -```graphql {2-3} title="Subgraph B" -type Position { - x: Int! - y: Int! -} -``` -<> - - - -Attempting to compose these two subgraph schemas together will [break composition](./composition/#breaking-composition). The router doesn't know which subgraph is responsible for resolving `Position.x` and `Position.y`. To enable multiple subgraphs to resolve these fields, you must first mark that field as [`@shareable`](#using-shareable). - - - -As an alternative, if you want Subgraphs A and B to resolve different fields of `Position`, you can designate the `Position` type as an [entity](../entities). - - - -### Using `@shareable` - -The `@shareable` directive enables multiple subgraphs to resolve a particular object field (or set of object fields). - -To use `@shareable` in a subgraph schema, you first need to add the following snippet to that schema to [opt in to Federation 2](../federation-2/moving-to-federation-2/#opt-in-to-federation-2): - -```graphql -extend schema - @link(url: "https://specs.apollo.dev/federation/v2.3", - import: ["@key", "@shareable"]) -``` - -Then you can apply the `@shareable` directive to an object type, or to individual fields of that type: - -

βœ…

- - - -```graphql {1} title="Subgraph A" -type Position @shareable { - x: Int! - y: Int! -} -``` - -```graphql {2-3} title="Subgraph B" -type Position { - x: Int! @shareable - y: Int! @shareable -} -``` -<> - - - - - -Marking a type as `@shareable` is equivalent to marking all of its fields as `@shareable`, so the two subgraph definitions above are equivalent. - - - -Both subgraphs A and B can now resolve the `x` and `y` fields for the `Position` type, and our subgraph schemas will successfully compose into a supergraph schema. - -#### ⚠️ Important considerations for `@shareable` - -* If a type or field is marked `@shareable` in any subgraph, it must be marked either `@shareable` or [`@external`](./federated-directives/#external) in every subgraph that defines it. Otherwise, composition fails. -* If multiple subgraphs can resolve a field, make sure each subgraph's resolver for that field behaves identically. Otherwise, queries might return inconsistent results depending on which subgraph resolves the field. - -#### Using `@shareable` with `extend` - -If you apply `@shareable` to an object type declaration, it only applies to the fields within that exact declaration. It does not apply to other declarations for that same type: - -```graphql title="Subgraph A" -type Position @shareable { - x: Int! # shareable - y: Int! # shareable -} - -extend type Position { - # highlight-start - z: Int! # ⚠️ NOT shareable! - # highlight-end -} -``` - -Using the `extend` keyword, the schema above includes two different declarations for `Position`. Because only the first declaration is marked `@shareable`, `Position.z` is not considered shareable. - -To make `Position.z` shareable, you can do one of the following: - -- Mark the individual field `z` with `@shareable`. - - ```graphql - extend type Position { - # highlight-start - z: Int! @shareable - # highlight-end - } - ``` - -- Mark the entire `extend` declaration with `@shareable`. - - - This strategy requires targeting v2.2 or later of the Apollo Federation specification in your subgraph schema. Earlier versions do not support applying `@shareable` to the same object type multiple times. - - ```graphql - extend schema - @link(url: "https://specs.apollo.dev/federation/v2.3", import: ["@shareable"]) #highlight-line - - extend type Position @shareable { #highlight-line - z: Int! - } - ``` - -## Differing shared fields - -Shared fields can only differ in their [return types](#return-types) and [arguments](#arguments) in specific ways. -If fields you want to share between subgraphs differ more than is permitted, use [entities](../entities) instead of shareable value types. - - -### Return types - -Let's say two subgraphs both define an `Event` object type with a `timestamp` field: - -

❌

- - - -```graphql {2} title="Subgraph A" -type Event @shareable { - timestamp: Int! -} -``` - -```graphql {2} title="Subgraph B" -type Event @shareable { - timestamp: String! -} -``` - - - -Subgraph A's `timestamp` returns an `Int`, and Subgraph B's returns a `String`. This is invalid. When composition attempts to generate an `Event` type for the supergraph schema, it fails due to an unresolvable conflict between the two `timestamp` field definitions. - -Next, look at these varying definitions for the `Position` object type: - -

βœ…

- - - -```graphql {2-3} title="Subgraph A" -type Position @shareable { - x: Int! - y: Int! -} -``` - -```graphql {2-3} title="Subgraph B" -type Position @shareable { - x: Int - y: Int -} -``` - -<> - - - -The `x` and `y` fields are non-nullable in Subgraph A, but they're nullable in Subgraph B. This is valid. Composition recognizes that it can use the following definition for `Position` in the supergraph schema: - - -```graphql title="Supergraph schema" -type Position { - x: Int - y: Int -} -``` - -This definition works for querying Subgraph A, because Subgraph A's definition is more restrictive than this (a non-nullable value is always valid for a nullable field). In this case, composition coerces Subgraph A's `Position` fields to satisfy the reduced restrictiveness of Subgraph B. - - - -Subgraph A's actual subgraph schema is not modified. Within Subgraph A, `x` and `y` remain non-nullable. - - - -### Arguments - -Arguments for a shared field can differ between subgraphs in certain ways: - -* If an argument is required in at least one subgraph, it can be optional in other subgraphs. It cannot be omitted. -* If an argument is optional in every subgraph where it's defined, it is technically valid to omit it in other subgraphs. However: - * ⚠️ If a field argument is omitted from any subgraph, that argument is omitted from the supergraph schema entirely. This means that clients can't provide the argument for that field. - -

βœ…

- - - -```graphql {3} title="Subgraph A" -type Building @shareable { - # Argument is required - height(units: String!): Int! -} -``` - -```graphql {3} title="Subgraph B" -type Building @shareable { - # Argument can be optional - height(units: String): Int! -} -``` - - - -

❌

- - - -```graphql {3} title="Subgraph A" -type Building @shareable { - # Argument is required - height(units: String!): Int! -} -``` - -```graphql {3} title="Subgraph B" -type Building @shareable { - # ⚠️ Argument can't be omitted! ⚠️ - height: Int! -} -``` - - - -

⚠️

- - - -```graphql {3} title="Subgraph A" -type Building @shareable { - # Argument is optional - height(units: String): Int! -} -``` - -```graphql {5} title="Subgraph B" -type Building @shareable { - # Argument can be omitted, BUT - # it doesn't appear in the - # supergraph schema! - height: Int! -} -``` - - - -For more information, see [Input types and field arguments](./composition#input-types-and-field-arguments). - -### Omitting fields - -Look at these two definitions of a `Position` object type: - -

⚠️

- - - -```graphql title="Subgraph A" -type Position @shareable { - x: Int! - y: Int! -} -``` - -```graphql title="Subgraph B" -type Position @shareable { - x: Int! - y: Int! - z: Int! -} -``` - - - -Subgraph B defines a `z` field, but Subgraph A doesn't. In this case, when composition generates the `Position` type for the supergraph schema, it includes all three fields: - - - -```graphql title="Supergraph schema" -type Position { - x: Int! - y: Int! - z: Int! -} -``` - -<> - - - -This definition works for Subgraph B, but it presents a problem for Subgraph A. Let's say Subgraph A defines the following `Query` type: - - - -```graphql title="Subgraph A" -type Query { - currentPosition: Position! -} -``` - -<> - - - -According to the hypothetical supergraph schema, the following query is valid against the supergraph: - -

❌

- - - -```graphql -query GetCurrentPosition { - currentPosition { - x - y - z # ⚠️ Unresolvable! ⚠️ - } -} -``` - -<> - - - -And here's the problem: if Subgraph B doesn't define `Query.currentPosition`, this query must be executed on Subgraph A. But Subgraph A is missing the `Position.z` field, so that field is unresolvable! - -Composition recognizes this potential problem, and it fails with an error. So how do we fix it? Check out [Solutions for unresolvable fields](./composition/#solutions-for-unresolvable-fields). - -## Adding new shared fields - -Adding a new field to a value type can cause composition issues, because it's challenging to add the field to all defining subgraphs at the same time. - -Let's say we're adding a `z` field to our `Position` value type, and we start with Subgraph A: - -

⚠️

- - - -```graphql {4} title="Subgraph A" -type Position @shareable { - x: Int! - y: Int! - z: Int! -} -``` - -```graphql title="Subgraph B" -type Position @shareable { - x: Int! - y: Int! -} -``` - - - -It's likely that when we attempt to compose these two schemas, composition will fail, because Subgraph B can't resolve `Position.z`. - -To incrementally add the field to all of our subgraphs without breaking composition, we can use the [`@inaccessible` directive](#using-inaccessible). - - -### Using `@inaccessible` - -If you apply the `@inaccessible` directive to a field, composition omits that field from your router's API schema. This helps you incrementally add a field to multiple subgraphs without breaking composition. - -To use `@inaccessible` in a subgraph, first make sure you include it in the `import` array of your Federation 2 opt-in declaration: - -```graphql {3} title="Subgraph A" -extend schema - @link(url: "https://specs.apollo.dev/federation/v2.3", - import: ["@key", "@shareable", "@inaccessible"]) -``` - -Then, whenever you add a new field to a value type, apply `@inaccessible` to that field if it isn't yet present in every subgraph that defines the value type: - - - -```graphql {4} title="Subgraph A" -type Position @shareable { - x: Int! - y: Int! - z: Int! @inaccessible -} -``` - -```graphql title="Subgraph B" -type Position @shareable { - x: Int! - y: Int! -} -``` - - - -Even if `Position.z` is defined in multiple subgraphs, you only need to apply `@inaccessible` in one subgraph to omit it. In fact, you might want to apply it in only one subgraph to simplify removing it later. - -With the syntax above, composition omits `Position.z` from the generated API schema, and the resulting `Position` type includes only `x` and `y` fields. - - - -Notice that `Position.z` does appear in the supergraph schema, but the API schema enforces which fields clients can include in operations. [Learn more about federated schemas.](./overview/) - - - -Whenever you're ready, you can now add `Position.z` to Subgraph B: - - - -```graphql title="Subgraph A" -type Position @shareable { - x: Int! - y: Int! - z: Int! @inaccessible -} -``` - -```graphql {4} title="Subgraph B" -type Position @shareable { - x: Int! - y: Int! - z: Int! -} -``` - - - -At this point, `Position.z` is still `@inaccessible`, so composition continues to ignore it. - -Finally, when you've added `Position.z` to every subgraph that defines `Position`, you can remove `@inaccessible` from Subgraph A: - - - -```graphql {4} title="Subgraph A" -type Position @shareable { - x: Int! - y: Int! - z: Int! -} -``` - -```graphql title="Subgraph B" -type Position @shareable { - x: Int! - y: Int! - z: Int! -} -``` - - - -Composition now successfully includes `Position.z` in the supergraph schema! - -## Unions and interfaces - -In Federation 2, `union` and `interface` type definitions can be shared between subgraphs by default, and those definitions can differ: - - -```graphql {1, 3, 9} title="Subgraph A" -union Media = Book | Movie - -interface User { - name: String! -} -``` - -```graphql {1, 3, 9} title="Subgraph B" -union Media = Book | Podcast - -interface User { - name: String! - age: Int! -} -``` - - - -[Compositional logic](./composition#merging-types-from-multiple-subgraphs) merges these definitions in your supergraph schema: - -```graphql title="Supergraph schema" -union Media = Book | Movie | Podcast - -# The object types that implement this interface are -# responsible for resolving these fields. -interface User { - name: String! - age: Int! -} -``` - -This can be useful when different subgraphs are responsible for different subsets of a particular set of related types or values. - - - -You can also use the `enum` type across multiple subgraphs. For details, see [Merging types from multiple subgraphs](composition#enums). - - - -### Challenges with shared interfaces - -Sharing an interface type across subgraphs introduces maintenance challenges whenever that interface changes. Consider these subgraphs: - - - -```graphql title="Subgraph A" -interface Media { - id: ID! - title: String! -} - -type Book implements Media { - id: ID! - title: String! -} -``` - -```graphql title="Subgraph B" -interface Media { - id: ID! - title: String! -} - -type Podcast implements Media { - id: ID! - title: String! -} -``` - - - -Now, let's say Subgraph B adds a `creator` field to the `Media` interface: - -

❌

- - - -```graphql title="Subgraph A" -interface Media { - id: ID! - title: String! -} - -type Book implements Media { - id: ID! - title: String! - # ❌ Doesn't define creator! -} -``` - -```graphql title="Subgraph B" -interface Media { - id: ID! - title: String! - creator: String! #highlight-line -} - -type Podcast implements Media { - id: ID! - title: String! - creator: String! #highlight-line -} -``` - - - -This breaks composition, because `Book` also implements `Media` but doesn't define the new `creator` field. - -To prevent this error, all implementing types across all subgraphs need to be updated to include all fields of `Media`. This becomes more and more challenging to do as your number of subgraphs and teams grows. Fortunately, there's a [solution](#solution-entity-interfaces). - -#### Solution: Entity interfaces - -Apollo Federation 2.3 introduces a powerful abstraction mechanism for interfaces, enabling you to add interface fields across subgraphs without needing to update every single implementing type. - -[Learn more about entity interfaces.](../entities/interfaces/) - -## Input types - -Subgraphs can share `input` type definitions, but composition merges their fields using an intersection strategy. When `input` types are composed across multiple subgraphs, only mutual fields are preserved in the supergraph schema: - - - -```graphql title="Subgraph A" -input UserInput { - name: String! - age: Int # Not in Subgraph B -} -``` - -```graphql title="Subgraph B" -input UserInput { - name: String! - email: String # Not in Subgraph A -} -``` - - - -Compositional logic merges only the fields that all `input` types have in common. To learn more, see [Merging input types and field arguments](./composition#input-types-and-field-arguments). - -```graphql title="Supergraph schema" -input UserInput { - name: String! -} -``` - -To learn more about how composition merges different schema types under the hood, see [Merging types during composition](./composition#merging-types-from-multiple-subgraphs). diff --git a/docs/source/federation-2/backward-compatibility.mdx b/docs/source/federation-2/backward-compatibility.mdx index de3cfff40..fa1bee5f1 100644 --- a/docs/source/federation-2/backward-compatibility.mdx +++ b/docs/source/federation-2/backward-compatibility.mdx @@ -12,15 +12,15 @@ Yes. As of 15 November 2022, `@apollo/gateway` v0.x is officially deprecated, wi ## Do I need to modify my subgraph schemas to use Federation 2? -Eventually. The process of [moving to Federation 2](./moving-to-federation-2/) has three steps: +Eventually. The process of [moving to Federation 2](/graphos/reference/migration/to-federation-version-2/) has three steps: -1. Upgrade your gateway to support Federation 2 (we recommend [moving to the GraphOS Router](/router/migrating-from-gateway/)). +1. Upgrade your gateway to support Federation 2 (we recommend [moving to the GraphOS Router](/graphos/reference/migration/from-gateway/)). 2. Begin composing your supergraph schema with Federation 2 composition logic. 3. Update your individual subgraphs to use Federation 2 features and directives. Steps 1 and 2 usually require no changes to your subgraph schemas. Schemas that do require changes are schemas that should cause certain composition errors that Federation 1 fails to detect ([see below.](#breaking-changes)). -Step 3 does require some changes to your subgraph schemas, described [here](./moving-to-federation-2/#step-3-update-individual-subgraphs). +Step 3 does require some changes to your subgraph schemas, described [here](/graphos/reference/migration/to-federation-version-2/#step-3-update-individual-subgraphs). ### Breaking changes @@ -186,11 +186,11 @@ The above `@provides` directives usage should break composition because it does No, not after you [convert at least one subgraph schema](#do-i-need-to-modify-my-subgraph-schemas-to-use-federation-2) to a true Federation 2 schema. -Federation 2 provides [more flexible composition rules](./new-in-federation-2/#more-flexible-composition) compared to Federation 1. After you modify your subgraph schemas to take advantage of this flexibility, your graph will no longer compose with Federation 1. You need to revert these changes to move back to Federation 1. +Federation 2 provides more flexible composition rules compared to Federation 1. After you modify your subgraph schemas to take advantage of this flexibility, your graph will no longer compose with Federation 1. You need to revert these changes to move back to Federation 1. ## Does `@apollo/gateway` v2 support Federation 1? -Yes. If you want, you can update your gateway's `@apollo/gateway` library to its latest `2.x` version before you're ready to [move your graph to Federation 2](./moving-to-federation-2/). +Yes. If you want, you can update your gateway's `@apollo/gateway` library to its latest `2.x` version before you're ready to [move your graph to Federation 2](/graphos/reference/migration/to-federation-version-2/). Your plugins and customizations for `@apollo/gateway` `0.x` will continue to work as expected in `@apollo/gateway` `2.x`. @@ -198,6 +198,6 @@ Your plugins and customizations for `@apollo/gateway` `0.x` will continue to wor | Router/Gateway version | Federation 1
Composition | Federation 2
Composition | |-|--------------|--------------| -| [Apollo Router Core](https://www.apollographql.com/docs/router/) v1.x | 🟒 | 🟒 | +| Apollo Router Core v1.x | 🟒 | 🟒 | | `@apollo/gateway` v2.x | 🟒 | 🟒 | | `@apollo/gateway` v0.x (deprecated) | 🟒 | ❌ | diff --git a/docs/source/federation-2/moving-to-federation-2.mdx b/docs/source/federation-2/moving-to-federation-2.mdx index 4dcf057da..42f0cc7ff 100644 --- a/docs/source/federation-2/moving-to-federation-2.mdx +++ b/docs/source/federation-2/moving-to-federation-2.mdx @@ -4,7 +4,7 @@ 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/) +> πŸ“£ If you haven't yet, [see what's new in Federation 2.](/graphos/reference/federation/versions#v20) You can (and should!) move your Apollo Federation 1 supergraph to Federation 2 incrementally, one component at a time. Your supergraph will work as expected after each step in the process, even while some of your subgraphs continue using Federation 1 schemas. @@ -23,7 +23,7 @@ graph LR; You can upgrade to either of the following: - - [The GraphOS Router](/router/), a high-performance precompiled executable (recommended) + - [The GraphOS Router](https://github.com/apollographql/router), a high-performance precompiled executable (recommended) - Version 2.x of the `@apollo/gateway` library, along with version 4.x of Apollo Server 2. Begin composing your supergraph schema with Federation 2 composition logic. 3. Update your individual subgraphs to use Federation 2 features and directives. @@ -52,8 +52,8 @@ Both the GraphOS Router and `@apollo/gateway` v2.x support Federation 1. You can ### Moving to the GraphOS Router -- To get started running the GraphOS Router, see the [quickstart](/router/quickstart/). -- For guidance on moving to the GraphOS Router from your Node.js-based gateway, see [this article](/router/migrating-from-gateway). +- To get started running the GraphOS Router, see the [overview](/graphos/routing/about-router). +- For guidance on moving to the GraphOS Router from your Node.js-based gateway, see [this article](/graphos/reference/migration/from-gateway). ### Upgrading `@apollo/gateway` and Apollo Server @@ -74,14 +74,14 @@ Apollo Server 3.x supports these updated library versions, however Apollo Server Federation 2 uses a completely new method to compose supergraph schemas. This method is backward compatible with Federation 1 subgraph schemas, and it provides the following benefits even for Federation 1 subgraphs: -- Helpful [composition hints](../hints/) when schema definitions are inconsistent between your subgraphs +- Helpful [composition hints](/graphos/reference/federation/hints) when schema definitions are inconsistent between your subgraphs - Support for interfaces implementing other interfaces (which Federation 1 composition doesn't support) Follow the instructions below to configure whichever composition method(s) you currently use: -If you're using [managed federation](../managed-federation/overview/), you move individual variants of your graph to Federation 2 via the GraphOS Studio UI. +If you use GraphOS to manage supergraph composition and deployment, you move individual variants of your graph to Federation 2 via the GraphOS Studio UI. Open the Settings page for the variant you want to move to Federation 2, then select the **This Variant** tab: @@ -154,7 +154,7 @@ Your Federation 1 subgraphs are now composed using Federation 2 composition. The -If your supergraph is not successfully composing with Federation 2, see [Breaking changes](./backward-compatibility/#breaking-changes) for the most common causes. +If your supergraph is not successfully composing with Federation 2, see [Breaking changes](/graphos/reference/migration/backward-compatibility#breaking-changes) for the most common causes. @@ -168,9 +168,9 @@ You can update your subgraphs one at a time. The steps below describe how to mod Federation 2 provides powerful new features that require making some changes to your subgraphs. These features include: -- Selectively sharing types and fields across subgraphs with [`@shareable`](../federated-schemas/federated-directives#shareable) -- Safely migrating fields from one subgraph to another with [`@override`](../federated-schemas/federated-directives#override) -- Hiding internal routing fields from graph consumers with [`@inaccessible`](../federated-schemas/federated-directives#inaccessible) +- Selectively sharing types and fields across subgraphs with [`@shareable`](/graphos/reference/federation/directives#shareable) +- Safely migrating fields from one subgraph to another with [`@override`](/graphos/reference/federation/directives#override) +- Hiding internal routing fields from graph consumers with [`@inaccessible`](/graphos/reference/federation/directives#inaccessible) The schema changes you make are not backward compatible with Federation 1, which means you won't be able to use Federation 1 composition anymore unless you revert those changes. @@ -184,7 +184,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](../building-supergraphs/compatible-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](/graphos/reference/federation/compatible-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 @@ -203,13 +203,13 @@ This definition identifies a schema as a Federation 2 schema, and it `import`s a Depending on your schema, you might need to add other federated directives to the `import` array, such as `@external` or `@provides`. -[See all Federation-specific directives.](../federated-schemas/federated-directives/) +[See all Federation-specific directives.](/graphos/reference/federation/directives/) ### Add directive definitions if needed -Currently, not all [subgraph libraries](../building-supergraphs/compatible-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](/graphos/reference/federation/compatible-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: @@ -234,7 +234,7 @@ Some subgraph libraries are "code-first" (they dynamically generate their schema -Definitions for all Federation 2 directives are available in [this article](../federated-schemas/federated-directives/). We work with library maintainers to help automatically add these schema definitions in as many subgraph libraries as possible. +Definitions for all Federation 2 directives are available in [this article](/graphos/reference/federation/directives/). We work with library maintainers to help automatically add these schema definitions in as many subgraph libraries as possible. ### Mark all value types as `@shareable` @@ -288,11 +288,11 @@ You can also apply `@shareable` directly to a type definition (such as `Position -For more details, see [Value types](../federated-schemas/sharing-types/). +For more details, see [Value types](/graphos/schema-design/federated-schemas/sharing-types/). ### Update entity definitions -Federation 2 introduces subtle but powerful changes to [entities](../entities/). These changes require corresponding updates to their definitions in your subgraph schemas. +Federation 2 introduces subtle but powerful changes to [entities](/graphos/get-started/guides/federate-schemas#entity-overview). These changes require corresponding updates to their definitions in your subgraph schemas. #### Remove unnecessary syntax @@ -346,7 +346,7 @@ Note the following in the Federation 2 subgraphs above: - The Inventory subgraph no longer `extend`s the `Product` entity. - The Inventory subgraph no longer marks the `Product.id` field as `@external`. - - The `@external` directive is no longer required for `@key` fields, but it is still required for [`@requires`](../entities/contribute-fields#contributing-computed-entity-fields) and [`@provides`](../entities/resolve-another-subgraphs-fields#using-provides). + - The `@external` directive is no longer required for `@key` fields, but it is still required for [`@requires`](/graphos/schema-design/federated-schemas/entities/contribute-fields#contributing-computed-entity-fields) and [`@provides`](/graphos/schema-design/federated-schemas/entities/resolve-another-subgraphs-fields#using-provides). - Both subgraphs can resolve `Product.id`, even though it isn't marked as `@shareable`! - Unlike most fields, `@key` fields such as `Product.id` are `@shareable` by default. This is necessary for `@key` fields, because the gateway uses them to associate data from different subgraphs with the same object. @@ -442,7 +442,7 @@ type Review { -Setting `resolvable: false` tells the gateway that a subgraph doesn't define a reference resolver for a particular entity. This is most common when [referencing an entity without contributing fields to it](../entities/#referencing-an-entity-without-contributing-fields). +Setting `resolvable: false` tells the gateway that a subgraph doesn't define a reference resolver for a particular entity. This is most common when [referencing an entity without contributing fields to it](/graphos/schema-design/federated-schemas/entities/contribute-fields#referencing-an-entity-without-contributing-fields). --- diff --git a/docs/source/federation-2/new-in-federation-2.mdx b/docs/source/federation-2/new-in-federation-2.mdx index be90b3578..012e2d208 100644 --- a/docs/source/federation-2/new-in-federation-2.mdx +++ b/docs/source/federation-2/new-in-federation-2.mdx @@ -4,11 +4,11 @@ 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/). +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](/graphos/reference/migration/to-federation-version-2/). -If you're just getting started with Federation, check out the [Quickstart](../quickstart/setup/). +If you're just getting started with Federation, check out the [Quickstart](/graphos/get-started/quickstart). @@ -17,11 +17,11 @@ If you're just getting started with Federation, check out the [Quickstart](../qu Before covering what's new, here's what isn't changing in Federation 2: * Most importantly, Federation 2 is backward compatible with most Federation 1 supergraphs. You can probably move your existing supergraph to use Federation 2 composition without making any changes. - * 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/). + * Graphs that do require changes are graphs that should cause composition errors, but Federation 1 fails to detect them. [Learn more.](/graphos/reference/migration/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](/graphos/reference/migration/to-federation-version-2/). -* Subgraph servers have no additional requirements. Any [subgraph-compatible library](../building-supergraphs/compatible-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. +* Subgraph servers have no additional requirements. Any [subgraph-compatible library](/graphos/reference/federation/compatible-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](/graphos/reference/migration/to-federation-version-2/#add-directive-definitions-if-needed) to use them in your subgraph schemas. ## More flexible composition @@ -55,7 +55,7 @@ type Book { In Federation 2, this "identical definition" constraint is removed. Value types and their fields can be shared across subgraphs, even if certain details differ between definitions. -For details, see the sections below, along with [Value types](../federated-schemas/sharing-types/). +For details, see the sections below, along with [Value types](/graphos/schema-design/federated-schemas/sharing-types/). ### Objects @@ -82,7 +82,7 @@ type Book @shareable { -The two `Book` type definitions above differ in terms of the fields they include and the nullability of those fields. Notice also the new [`@shareable`](../federated-schemas/sharing-types/#using-shareable) directive, which is required to indicate that a field can be resolved by multiple subgraphs. +The two `Book` type definitions above differ in terms of the fields they include and the nullability of those fields. Notice also the new [`@shareable`](/graphos/schema-design/federated-schemas/sharing-types/#using-shareable) directive, which is required to indicate that a field can be resolved by multiple subgraphs. @@ -95,17 +95,17 @@ This flexibility is especially helpful when an organization has multiple standal #### Valid shared field differences between subgraphs * The return type of a shared field can vary in nullability (`String` / `String!`). -* Types can omit fields that are included in other subgraphs, as long as every field in your supergraph is always resolvable. (For details, see [Rules of composition](../federated-schemas/composition/#rules-of-composition).) +* Types can omit fields that are included in other subgraphs, as long as every field in your supergraph is always resolvable. (For details, see [Rules of composition](/graphos/reference/federation/composition-rules).) -For details on how these field differences are handled, see [Differing shared fields](../federated-schemas/sharing-types/#differing-shared-fields). +For details on how these field differences are handled, see [Differing shared fields](/graphos/schema-design/federated-schemas/sharing-types/#differing-shared-fields). ### Enums, unions, and interfaces -In Federation 2, `enum`, `union`, and `interface` definitions can differ between subgraphs. For details, see [Merging types from multiple subgraphs](../federated-schemas/composition/#merging-types-from-multiple-subgraphs). +In Federation 2, `enum`, `union`, and `interface` definitions can differ between subgraphs. For details, see [Merging types from multiple subgraphs](/graphos/reference/federation/composition-rules#merging-types-from-multiple-subgraphs). ## Entities -Federation 2 introduces subtle but powerful changes to [entities](../entities/). +Federation 2 introduces subtle but powerful changes to [entities](/graphos/get-started/guides/federate-schemas#entity-overview). ### Originating subgraphs @@ -155,7 +155,7 @@ type Product @key(fields: "id") { -For details, see [Contributing entity fields](../entities/#contributing-entity-fields). +For details, see [Contributing entity fields](/graphos/schema-design/federated-schemas/entities/contribute-fields). ### Shared entity fields @@ -183,11 +183,11 @@ type Product @key(fields: "id") { -For more information, see [Resolving another subgraph's field](../entities/resolve-another-subgraphs-fields). +For more information, see [Resolving another subgraph's field](/graphos/schema-design/federated-schemas/entities/resolve-another-subgraphs-fields). ### Changes to `@key` -Federation 2 adds a new optional argument to the `@key` directive: `resolvable`. You can set this argument to `false` to indicate that a particular subgraph doesn't define a [reference resolver](../entities/#2-define-a-reference-resolver) for that entity. +Federation 2 adds a new optional argument to the `@key` directive: `resolvable`. You can set this argument to `false` to indicate that a particular subgraph doesn't define a [reference resolver](/graphos/get-started/guides/federate-schemas#2-define-a-reference-resolver) for that entity. For example: @@ -218,11 +218,11 @@ type Review { In this case, the Reviews subgraph references the `Product` entity by using it as the return type for `Review.product`. However, the subgraph doesn't contribute any unique fields to `Product`, so it doesn't need to define a reference resolver for it. Therefore, the "stub" definition of `Product` in the Reviews subgraph can include `resolvable: false`. -For more information, see [Referencing an entity without contributing fields](../entities/#referencing-an-entity-without-contributing-fields). +For more information, see [Referencing an entity without contributing fields](/graphos/schema-design/federated-schemas/entities/contribute-fields#contributing-computed-entity-fields). ### Migrating fields -Federation 2 introduces the [`@override` directive](../federated-schemas/federated-directives/#override), which helps you safely migrate entity and root-level fields between subgraphs with managed federation: +Federation 2 introduces the [`@override` directive](/graphos/reference/federation/directives/#override), which helps you safely migrate entity and root-level fields between subgraphs with managed federation: @@ -246,7 +246,7 @@ type Bill @key(fields: "id") { -For details, see [Entity migration](../entities/migrate-fields). +For details, see [Entity migration](/graphos/schema-design/federated-schemas/entities/migrate-fields). ## Interfaces implementing interfaces diff --git a/docs/source/federation-versions.mdx b/docs/source/federation-versions.mdx index 0bd370106..815705ef8 100644 --- a/docs/source/federation-versions.mdx +++ b/docs/source/federation-versions.mdx @@ -4,7 +4,7 @@ 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-schemas/federated-directives/). +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](/graphos/reference/federation/directives/). For a comprehensive changelog for Apollo Federation and its associated libraries, see [GitHub](https://github.com/apollographql/federation/blob/main/CHANGELOG.md). @@ -20,11 +20,11 @@ For a comprehensive changelog for Apollo Federation and its associated libraries - Before you increment a subgraph's federation version, update your router and build pipeline. For details, see [Updating your graph safely](/graphos/graphs/updating/). + Before you increment a subgraph's federation version, update your router and build pipeline. For details, see [Updating your graph safely](/graphos/platform/graph-management/updates). -- If you maintain a [subgraph-compatible library](./building-supergraphs/compatible-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). +- If you maintain a [subgraph-compatible library](/graphos/reference/federation/compatible-subgraphs), consult this article to stay current with recently added directives. All of these directive definitions are also listed in the [subgraph specification](/graphos/reference/federation/subgraph-spec/#subgraph-schema-additions). ## v2.9 @@ -71,7 +71,7 @@ Minimum router version -Introduced. [Learn more](./federated-schemas/federated-directives/#cost). +Introduced. [Learn more](/federation/federated-schemas/federated-directives#cost). ```graphql directive @cost(weight: Int!) on ARGUMENT_DEFINITION | ENUM | FIELD_DEFINITION | INPUT_FIELD_DEFINITION | OBJECT | SCALAR @@ -88,7 +88,7 @@ directive @cost(weight: Int!) on ARGUMENT_DEFINITION | ENUM | FIELD_DEFINITION | -Introduced. [Learn more](./federated-schemas/federated-directives/#listsize). +Introduced. [Learn more](/federation/federated-schemas/federated-directives#listsize). ```graphql directive @listSize(assumedSize: Int, slicingArguments: [String!], sizedFields: [String!], requireOneSlicingArgument: Boolean = true) on FIELD_DEFINITION @@ -153,7 +153,7 @@ Minimum router version -Introduced. [Learn more](./federated-schemas/federated-directives/#context). +Introduced. [Learn more](/graphos/reference/federation/directives/#context). ```graphql directive @context(name: String!) on OBJECT | INTERFACE | UNION; @@ -170,7 +170,7 @@ directive @context(name: String!) on OBJECT | INTERFACE | UNION; -Introduced. [Learn more](./federated-schemas/federated-directives/#fromcontext). +Introduced. [Learn more](/graphos/reference/federation/directives/#fromcontext). ```graphql scalar ContextFieldValue; @@ -237,7 +237,7 @@ Minimum router version -Added progressive `@override`. [Learn more.](./federated-schemas/federated-directives/#progressive-override) +Added progressive `@override`. [Learn more.](/graphos/reference/federation/directives/#progressive-override) ```graphql directive @override(from: String!, label: String) on FIELD_DEFINITION @@ -303,7 +303,7 @@ Minimum router version -Introduced. [Learn more.](/router/configuration/authorization) +Introduced. [Learn more.](/graphos/routing/security/authorization) ```graphql directive @policy(policies: [[federation__Policy!]!]!) on @@ -400,7 +400,7 @@ Minimum router version -Introduced. [Learn more.](/router/configuration/authorization) +Introduced. [Learn more.](/graphos/routing/security/authorization) ```graphql directive @authenticated on @@ -423,7 +423,7 @@ directive @authenticated on -Introduced. [Learn more.](/router/configuration/authorization) +Introduced. [Learn more.](/graphos/routing/security/authorization) ```graphql directive @requiresScopes(scopes: [[federation__Scope!]!]!) on @@ -520,7 +520,7 @@ Subscriptions - Composition now supports defining the `Subscription` type in subgraph schemas. -- Use of GraphQL subscriptions with a federated graph requires a compatible version of the GraphOS Router. [See details.](/router/executing-operations/subscription-support/#prerequisites) +- Use of GraphQL subscriptions with a federated graph requires a compatible version of the GraphOS Router. [See details.](/graphos/routing/operations/subscriptions/#prerequisites) @@ -581,7 +581,7 @@ Minimum router version -Introduced. [Learn more.](./entities/interfaces) +Introduced. [Learn more.](/graphos/schema-design/federated-schemas/entities/interfaces) ```graphql directive @interfaceObject on OBJECT @@ -598,7 +598,7 @@ directive @interfaceObject on OBJECT -Can now be applied to interface definitions to support [entity interfaces](./entities/interfaces/). +Can now be applied to interface definitions to support [entity interfaces](/graphos/schema-design/federated-schemas/entities/interfaces/). (Previous versions of composition threw an error if `@key` was applied to an interface definition.) @@ -728,7 +728,7 @@ Minimum router version -Introduced. [Learn more.](./federated-schemas/federated-directives#composedirective) +Introduced. [Learn more.](/graphos/reference/federation/directives#composedirective) ```graphql directive @composeDirective(name: String!) repeatable on SCHEMA @@ -745,7 +745,7 @@ directive @composeDirective(name: String!) repeatable on SCHEMA -The `fields` argument can now include fields that themselves take arguments. [Learn more.](./entities/contribute-fields/#using-requires-with-fields-that-take-arguments) +The `fields` argument can now include fields that themselves take arguments. [Learn more.](/graphos/schema-design/federated-schemas/entities/contribute-fields#using-requires-with-fields-that-take-arguments) (Functionality added in v2.1.2) @@ -811,7 +811,7 @@ extend schema The `import` list of this definition must include each federation-specific directive that the subgraph schema uses. In the example above, the schema uses `@key` and `@shareable`. -For details on these directives as defined in Federation 2, see [Federation-specific GraphQL directives](./federated-schemas/federated-directives/). +For details on these directives as defined in Federation 2, see [Federation-specific GraphQL directives](/graphos/reference/federation/directives/). @@ -978,7 +978,7 @@ Value types diff --git a/docs/source/hints.mdx b/docs/source/hints.mdx index 9034cee1a..a07032e35 100644 --- a/docs/source/hints.mdx +++ b/docs/source/hints.mdx @@ -4,7 +4,7 @@ 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-schemas/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/). +When you successfully compose your subgraph schemas into a supergraph schema, the composition process can flag potential improvements or hints. Hints are violations of the [GraphOS schema linter's](/graphos/platform/schema-management/linting) [composition rules](/graphos/platform/schema-management/linting/rules#composition-rules). You can review them on the [Checks](/graphos/platform/schema-management/checks) page in GraphOS Studio or via the [Rover CLI](/rover/). @@ -12,9 +12,9 @@ Composition hints only appear in GraphOS Studio and via the `rover subgraph chec -The [`rover subgraph check`](/rover/commands/subgraphs#subgraph-check) command outputs rule violations with the [severity levels](/graphos/delivery/schema-linter/#setting-severity-levels) you've configured for your graph variant. The [`rover supergraph compose`](/rover/commands/supergraphs#supergraph-compose) command outputs rule violations for all local subgraph schemas. +The [`rover subgraph check`](/rover/commands/subgraphs#subgraph-check) command outputs rule violations with the [severity levels](/graphos/platform/schema-management/linting/#setting-severity-levels) you've configured for your graph variant. The [`rover supergraph compose`](/rover/commands/supergraphs#supergraph-compose) command outputs rule violations for all local subgraph schemas. -See below for a list of composition rules categorized by rule type. The heading for each rule is the code that GraphOS returns for the rule violation. Refer to the [rules reference page](/graphos/delivery/linter-rules) for a comprehensive list of linter rules. +See below for a list of composition rules categorized by rule type. The heading for each rule is the code that GraphOS returns for the rule violation. Refer to the [rules reference page](/graphos/platform/schema-management/linting/rules) for a comprehensive list of linter rules. ### Inconsistent elements diff --git a/docs/source/index.mdx b/docs/source/index.mdx deleted file mode 100644 index 4d66cb665..000000000 --- a/docs/source/index.mdx +++ /dev/null @@ -1,173 +0,0 @@ ---- -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 services into a unified, federated GraphQL API using a microservices architecture. ---- - - - -## What is Apollo Federation? - -Apollo Federation lets you declaratively combine multiple GraphQL APIs into a single, federated graph. This federated graph enables clients to interact with multiple APIs through a single request. - -A client makes a request to the single entry point of the federated graph called the _router_. The router intelligently orchestrates and distributes the request across your APIs and returns a unified response. For a client, the request and response cycle of querying the router looks the same as querying any GraphQL server. - -```mermaid -graph LR; - clients(Clients); - router([Router]); - serviceA[GraphQL API
A]; - serviceB[GraphQL API
B]; - serviceC[GraphQL API
C]; - router --- serviceA & serviceB & serviceC; - clients -.- router; - class clients secondary; -``` - - - -To jump into building a federated GraphQL API, check out the [Apollo Federation Quickstart](./quickstart). - - - -## Benefits of federation - -### Microservices architecture - -Apollo Federation lets API teams operate in a [microservices architecture](https://www.atlassian.com/microservices/microservices-architecture/microservices-vs-monolith) while exposing a unified GraphQL API to clients. Understanding these concepts can help you get the most out of federation. - - - -- Learn more about the [considerations and benefits of GraphQL](https://www.apollographql.com/docs/intro/benefits). -- Learn more about the [considerations and benefits of microservices architecture](https://aws.amazon.com/compare/the-difference-between-monolithic-and-microservices-architecture/). - - - -### Preserve client simplicity and performance - -A client may need to make multiple requests when interacting with multiple non-federated GraphQL APIs. This can happen when an organization adopting GraphQL has multiple teams developing APIs independently. Each team sets up a GraphQL API that provides the data used by that team. For example, a travel app may have separate GraphQL APIs for users, flights, and hotels: - -```mermaid -graph RL; - subgraph " "; - databaseA[(User
data)]; - serviceA[Users API]; - databaseA --- serviceA; - end; - - subgraph " "; - databaseB[(Flight
data)]; - serviceB[Flights API]; - databaseB --- serviceB; - end; - - subgraph " "; - databaseC[(Hotel
data)]; - serviceC[Hotels API]; - databaseC --- serviceC; - end; - - clients(Clients); - serviceA & serviceB & serviceC -.- clients; - class clients secondary; -``` - -With a single federated graph, you preserve a powerful advantage of GraphQL over traditional REST APIs: the ability to fetch all the data you need in a single request. - -```mermaid -graph LR; - clients(Clients); - subgraph supergraph[" "]; - router([Router]); - serviceA[Users API]; - serviceB[Flights API]; - serviceC[Hotels API]; - databaseA[(Users
data)]; - databaseB[(Flights
data)]; - databaseC[(Hotels
data)]; - serviceA --- databaseA; - serviceB --- databaseB; - serviceC --- databaseC; - router --- serviceA & serviceB & serviceC; - end; - clients -.- router; - class clients secondary; -``` - -The router intelligently calls all the APIs it needs to complete requests rather than simply forwarding them. -For performance and security reasons, clients should only query the router, and only the router should query the constituent APIs. -No client-side configuration is required. - -### Design schemas at scale - -Some alternative approaches to combining GraphQL APIs impose limits on your schema, like adding namespaces or representing relationships with IDs instead of types. With these approaches, your individual GraphQL API schemas may look unchangedβ€”but the resulting federated schema that clients interact with is more complex. Subsequently, it requires you to make frontend as well as backend changes. - -With Apollo Federation, clients can interact with the federated schema as if it were a monolith. Consumers of your API shouldn't know or care that it's implemented as microservices. - -### Maintain a single API - -With federation, every team contributes directly to the overall federated GraphQL schema. Each team can work independently without needing to maintain multiple API layers. This frees your platform team to focus on the quality of your API rather than keeping it up to date. - - -## Next steps - -Before continuing, it's helpful to know some terminology: - -- When combining multiple GraphQL APIs, the single, federated graph is called a _supergraph_. -- In a supergraph, the individual GraphQL APIs are called _subgraphs_. - -```mermaid -graph LR; - clients(Clients); - router([Router]); - subgraph "Supergraph" - serviceA[Subgraph
A]; - serviceB[Subgraph
B]; - serviceC[Subgraph
C]; - router --- serviceA & serviceB & serviceC; - end - clients -.- router; - class clients secondary; -``` - -Different subgraphs in the same supergraph can use different server implementations and even different programming languages as long as they are [federation-compatible](./building-supergraphs/compatible-subgraphs/). - - - -- Learn more about [choosing subgraph libraries](./building-supergraphs/subgraphs-overview#choosing-a-subgraph-library). -- Learn more about [your router options](./building-supergraphs/router). - - - -### Additional resources - -Depending on your goals, you have several options for learning more about federation: -- If you're new to federated architecture, this [overview article](https://graphql.com/learn/federated-architecture/) can familiarize the concepts. -- If you'd like to recap the key concepts of Apollo Federation, the video below gives a great overview. - - - - - - - -- If you learn best by doing, this [interactive course](https://www.apollographql.com/tutorials/voyage-part1) teaches you to build an example supergraph using Apollo Federation. - -### Further documentation - -Once you're ready to apply federation to your own APIs, these docs sections can help you get started: - -- [Quickstart](./quickstart) to get you up and running with a federated graph -- Conceptual overview of [Federated Schemas](./federated-schemas) -- Reference materials for: - - [Performance considerations](./performance/caching) - - [Debugging and metrics](./errors) - - [Subgraph specifications](./building-supergraphs/router) for federation-compatibility - -### Best practices - -Whether your supergraph implementation is already underway or just starting, you can use the [Supergraph Architecture Framework](/graphos/enterprise/supergraph-architecture-framework/) (SAF) to learn about best practices. The SAF includes an assessment to quantify your supergraph's current state and identify areas for improvement. diff --git a/docs/source/managed-federation/deployment.mdx b/docs/source/managed-federation/deployment.mdx index 3abb9971c..3e088dcbb 100644 --- a/docs/source/managed-federation/deployment.mdx +++ b/docs/source/managed-federation/deployment.mdx @@ -4,7 +4,7 @@ subtitle: 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: +When rolling out changes to a subgraph, we recommend the following workflow: 1. Confirm the backward compatibility of each change by [running `rover subgraph check`](/rover/commands/subgraphs/#validating-subgraph-schema-changes) in your CI pipeline. 2. Merge backward compatible changes that successfully pass schema checks. @@ -21,7 +21,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](/graphos/delivery/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](/graphos/platform/schema-management/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. @@ -122,15 +122,15 @@ The next time it starts up or polls, your router obtains an updated configuratio ## Advanced deployment workflows -With managed federation, you can control which version of your schema your router fleet uses. In most cases, rolling over all of your router instances to a new schema version is safe, assuming you've used [schema checks](./federated-schema-checks/) to confirm that your changes are backward compatible. Your deployment model, however, may require an advanced workflow to deploy a specific version of a schema. +With managed federation, you can control which version of your schema your router fleet uses. In most cases, rolling over all of your router instances to a new schema version is safe, assuming you've used [schema checks](/graphos/platform/schema-management/checks/) to confirm that your changes are backward compatible. Your deployment model, however, may require an advanced workflow to deploy a specific version of a schema. Two types of advanced deployment workflows: -* **Blue-green deployment workflow**. For deployments that require progressive rollout, such as blue-green deployments, you can configure your environments to refer to a single [graph variant](/graphos/graphs/#variants) by pinning each environment's supergraph schema to your routers at deployment time. Using a single variant between different production environments enables GraphOS Studio to get usage reports and analyze the combined production traffic of all environments, as well as providing a consistent changelog of your schema over time. +* **Blue-green deployment workflow**. For deployments that require progressive rollout, such as blue-green deployments, you can configure your environments to refer to a single [graph variant](/graphos/get-started/concepts/graphs-and-variants#variants) by pinning each environment's supergraph schema to your routers at deployment time. Using a single variant between different production environments enables GraphOS Studio to get usage reports and analyze the combined production traffic of all environments, as well as providing a consistent changelog of your schema over time. -* **Graph variant workflow**. Changes at the router level might involve a variety of different updates, such as [migrating entities](../entities/migrate-fields) from one subgraph to another. If your infrastructure requires a more advanced deployment process to handle the different router updates, you can use [graph variants](/graphos/graphs/#variants) to manage router fleets running with different configurations. +* **Graph variant workflow**. Changes at the router level might involve a variety of different updates, such as [migrating entities](/graphos/schema-design/federated-schemas/entities/migrate-fields) from one subgraph to another. If your infrastructure requires a more advanced deployment process to handle the different router updates, you can use [graph variants](/graphos/get-started/concepts/graphs-and-variants#variants) to manage router fleets running with different configurations. - A common use for graph variants is [contracts](/graphos/delivery/contracts/), for example, to create separate contract variants for the public and private APIs of a supergraph schema. + A common use for graph variants is [contracts](/graphos/platform/schema-management/delivery/contracts/overview), for example, to create separate contract variants for the public and private APIs of a supergraph schema. ### Example blue-green deployment @@ -138,7 +138,7 @@ Two types of advanced deployment workflows: A blue-green deployment strategy uses two environments: one environment (blue) serves the schema variant for live traffic, and the other environment (green) uses a variant for a new release that's under development. When the new release is ready, traffic is migrated from the blue to the green environment. This cycle repeats with each new release. -As an example, follow these steps to deploy with a supergraph schema of a new release (green) environment; the example uses the [GraphOS Platform API](/graphos/platform-api/) to perform custom GraphOS actions: +As an example, follow these steps to deploy with a supergraph schema of a new release (green) environment; the example uses the [GraphOS Platform API](/graphos/reference/platform-api/) to perform custom GraphOS actions: 1. Publish all the release's subgraphs at once using the Platform API [`publishSubgraphs` mutation](https://studio.apollographql.com/graph/apollo-platform/variant/main/schema/reference/objects/GraphMutation#publishSubgraphs). @@ -171,7 +171,7 @@ As an example, follow these steps to deploy with a supergraph schema of a new re } ``` - This initiates a [launch](/graphos/delivery/launches/), as well as any downstream launches necessary for [contracts](/graphos/delivery/contracts/#automatic-updates). It returns the launch IDs, with downstream launch IDs configured to return synchronously (`downstreamLaunchInitiation: "SYNC"`) with the mutation. + This initiates a [launch](/graphos/platform/schema-management/delivery/launch/), as well as any downstream launches necessary for [contracts](/graphos/platform/schema-management/delivery/contracts/create/#automatic-updates). It returns the launch IDs, with downstream launch IDs configured to return synchronously (`downstreamLaunchInitiation: "SYNC"`) with the mutation. @@ -231,11 +231,11 @@ As an example, follow these steps to deploy with a supergraph schema of a new re -4. Deploy your routers with the [`-s` or `--supergraph` option](/router/configuration/overview/#-s----supergraph) to specify the supergraph schema. +4. Deploy your routers with the [`-s` or `--supergraph` option](/graphos/reference/router/configuration#-s----supergraph) to specify the supergraph schema. * Specifying the `-s` or `--supergraph` option disables polling for the schema from Uplink. - * For an example using the option in a `docker run` command, see [Specifying the supergraph](/router/containerization/docker/#specifying-the-supergraph). + * For an example using the option in a `docker run` command, see [Specifying the supergraph](/graphos/routing/self-hosted/containerization/docker#specifying-the-supergraph). 5. If you need to roll back to a previous blue-green deployment, ensure the previous deployment is available and shift traffic back to the previous deployment. @@ -284,7 +284,7 @@ To configure a canary deployment for the `prod` graph variant: } ``` - This initiates a [launch](/graphos/delivery/launches/), as well as any downstream launches necessary for [contracts](/graphos/delivery/contracts/#automatic-updates). It returns the launch IDs, with downstream launch IDs configured to return synchronously (`downstreamLaunchInitiation: "SYNC"`) with the mutation. + This initiates a [launch](/graphos/platform/schema-management/delivery/launch/), as well as any downstream launches necessary for [contracts](/graphos/platform/schema-management/delivery/contracts/create/#automatic-updates). It returns the launch IDs, with downstream launch IDs configured to return synchronously (`downstreamLaunchInitiation: "SYNC"`) with the mutation. @@ -344,11 +344,11 @@ To configure a canary deployment for the `prod` graph variant: -4. Deploy your routers with the [`-s` or `--supergraph` option](/router/configuration/overview/#-s----supergraph) to specify the supergraph schema. +4. Deploy your routers with the [`-s` or `--supergraph` option](/graphos/reference/router/configuration#-s----supergraph) to specify the supergraph schema. * Specifying the `-s` or `--supergraph` option disables polling for the schema from Uplink. - * For an example using the option in a `docker run` command, see [Specifying the supergraph](/router/containerization/docker/#specifying-the-supergraph). + * For an example using the option in a `docker run` command, see [Specifying the supergraph](/graphos/routing/self-hosted/containerization/docker#specifying-the-supergraph). 5. If you need to roll back, ensure the previous deployment is available and shift traffic back to the live deployment. @@ -358,7 +358,7 @@ To configure a canary deployment for the `prod` graph variant: * If a previous deployment can't be redeployed, repeat steps 3 and 4 with the `launchID` you want to roll back to. Ensure the deployed subgraphs are compatible with the supergraph schema, then redeploy the router with a newly fetched supergraph schema for your target `launchID`. Before considering only rolling back the supergraph schema, see its [caveats](#roll-back-supergraph-schema-only). -With your canary deployment [reporting metrics to GraphOS](/graphos/metrics/), you can use [GraphOS Studio](https://studio.apollographql.com?referrer=docs-content) to verify a canary's performance before rolling out changes to the rest of the graph. +With your canary deployment [reporting metrics to GraphOS](/graphos/platform/insights/collection), you can use [GraphOS Studio](https://studio.apollographql.com?referrer=docs-content) to verify a canary's performance before rolling out changes to the rest of the graph. ## Modifying query-planning logic @@ -452,7 +452,7 @@ When rolling back a deployment, you must ensure the supergraph schema and router ### Roll forward to revert -Rollbacks are typically implemented by rolling forward to a new version that reverts the changes in the subgraph code repository, then performing the full release process (publishing the subgraph schema and rolling out the new code together) as outlined in the [change management tech note](/technotes/TN0028-change-management/#rollbacks-1). This ensures the supergraph schema exposed by the router matches the underlying subgraphs. It's the safest approach when using the standard [schema delivery pipeline](/graphos/delivery) where Apollo Uplink provides the supergraph schema to the router for continuous deployment of new [launches](/graphos/delivery/launches). +Rollbacks are typically implemented by rolling forward to a new version that reverts the changes in the subgraph code repository, then performing the full release process (publishing the subgraph schema and rolling out the new code together) as outlined in the [change management tech note](/technotes/TN0028-change-management/#rollbacks-1). This ensures the supergraph schema exposed by the router matches the underlying subgraphs. It's the safest approach when using the standard [schema delivery pipeline](/graphos/platform/schema-management) where Apollo Uplink provides the supergraph schema to the router for continuous deployment of new [launches](/graphos/platform/schema-management/delivery/launch). ### Roll back entire deployment @@ -472,7 +472,7 @@ A summary of rollback guidelines: - Any rollback must ensure the router's supergraph schema is compatible with the underlying subgraphs deployed in the target environment. -- GraphOS's standard CI/CD [schema delivery pipeline](/graphos/delivery) is the best choice for most environments seeking continuous deployment and empowerment of subgraph teams to ship both independently and with the safety of GraphOS checks to prevent breaking changes. For details, see the [change management tech note](/technotes/TN0028-change-management). +- GraphOS's standard CI/CD [schema delivery pipeline](/graphos/platform/schema-management) is the best choice for most environments seeking continuous deployment and empowerment of subgraph teams to ship both independently and with the safety of GraphOS checks to prevent breaking changes. For details, see the [change management tech note](/technotes/TN0028-change-management). - In environments with existing blue-green or canary deployments that rely on an immutable infrastructure approach—where no in-place updates, patches, or configuration changes can be made on production workloads—the router image can use an embedded supergraph schema. The supergraph schema is set for the router with the `--supergraph` flag for a specific GraphOS `launchID` that's generated by publishing the subgraph schemas for the specific subgraph image versions used in a blue-green or canary deployment. In this way, a blue-green or canary deployment can be made immutable as a whole, so rolling back to a previous deployment ensures the router's supergraph schema is compatible with the underlying subgraphs deployed in the target environment. diff --git a/docs/source/managed-federation/federated-schema-checks.mdx b/docs/source/managed-federation/federated-schema-checks.mdx index 3d2081a0a..d664c68e6 100644 --- a/docs/source/managed-federation/federated-schema-checks.mdx +++ b/docs/source/managed-federation/federated-schema-checks.mdx @@ -6,7 +6,7 @@ description: Use GraphOS schema checks and the Rover CLI to enable independent a -For an introduction to schema checks, see [Schema checks](/graphos/delivery/schema-checks/). +For an introduction to schema checks, see [Schema checks](/graphos/platform/schema-management/checks). @@ -30,7 +30,7 @@ There are two types of failures that can occur during validation: failed usage c - Failed usage checks are failures due to breaking changes, like removing a field that an active client is querying. - Failed composition is a failure due to inability to compose the graph, like missing a required `@key` for an entity. -In most cases, you should run `rover subgraph publish` only after a successful run of `rover subgraph check`. However, certain workflows require intentionally publishing a subgraph schema that fails composition (such as [migrating an entity or field between subgraphs](../entities/migrate-fields)). +In most cases, you should run `rover subgraph publish` only after a successful run of `rover subgraph check`. However, certain workflows require intentionally publishing a subgraph schema that fails composition (such as [migrating an entity or field between subgraphs](/graphos/schema-design/federated-schemas/entities/migrate-fields)). Even after `rover subgraph check` succeeds, however, it's possible that `rover subgraph publish` encounters composition errors because of simultaneous changes to another subgraph. When this occurs, your subgraph's registered schema is still updated as long as it is spec-compliant. However, the supergraph schema is not updated. This means that your router's configuration is also not updated. diff --git a/docs/source/managed-federation/overview.mdx b/docs/source/managed-federation/overview.mdx index 1d4a4df96..6e733a065 100644 --- a/docs/source/managed-federation/overview.mdx +++ b/docs/source/managed-federation/overview.mdx @@ -6,13 +6,13 @@ description: Use Apollo GraphOS to manage your supergraph including schema valid import ManagedFederationDiagram from '../../shared/diagrams/managed-federation.mdx'; -[Apollo GraphOS](/graphos/) provides managed federation support for graphs that use Apollo Federation. +Apollo GraphOS provides managed federation support for graphs that use Apollo Federation. With managed federation, you maintain subgraphs and delegate GraphOS to manage CI/CD tasks including the validation, composition, and update of your supergraph: -* Your subgraphs publish their schemas to GraphOS, which stores them in its schema registry. GraphOS then [validates](./federated-schema-checks) and [composes](../federated-schemas/composition/) them into a supergraph schema. +* Your subgraphs publish their schemas to GraphOS, which stores them in its schema registry. GraphOS then [validates](/graphos/platform/schema-management/checks) and [composes](/graphos/schema-design/federated-schemas/composition) them into a supergraph schema. -* Your routers can poll GraphOS—specifically, its [Apollo Uplink](./uplink) endpoint—to get the latest validated supergraph schema and other configurations. +* Your routers can poll GraphOS—specifically, its [Apollo Uplink](/graphos/routing/uplink) endpoint—to get the latest validated supergraph schema and other configurations. @@ -38,4 +38,4 @@ By using a configuration manager that's external to your router, you help ensure
-Ready to try it out? Continue to [Setup](./setup/). +Ready to try it out? Continue to [Setup](/graphos/get-started/quickstart). diff --git a/docs/source/managed-federation/setup.mdx b/docs/source/managed-federation/setup.mdx index 6b1d362e7..531b761cb 100644 --- a/docs/source/managed-federation/setup.mdx +++ b/docs/source/managed-federation/setup.mdx @@ -4,17 +4,17 @@ 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. +This article describes how to connect your supergraph to Apollo GraphOS to enable managed federation features. -As with all changes, you should first set up managed federation in a non-production environment, such as staging. To support this, you can create multiple [variants](/graphos/graphs/#variants) of your supergraph in GraphOS Studio. Each variant represents a distinct version of the same graph for different environments. +As with all changes, you should first set up managed federation in a non-production environment, such as staging. To support this, you can create multiple [variants](/graphos/get-started/concepts/graphs-and-variants#variants) of your supergraph in GraphOS Studio. Each variant represents a distinct version of the same graph for different environments. ## 1. Get started -First, complete the **Set up Apollo tools** step from [this tutorial](/graphos/quickstart/self-hosted#1-set-up-apollo-tools), including: +First, set up the tools required from [this tutorial](/graphos/get-started/quickstart), including: - Creating an Apollo account - Creating a graph in Studio @@ -22,7 +22,7 @@ First, complete the **Set up Apollo tools** step from [this tutorial](/graphos/q ## 2. Publish all subgraph schemas -In a supergraph architecture, each of your [subgraphs](../building-supergraphs/subgraphs-overview/) uses the Rover CLI to publish its schema to GraphOS: +In a supergraph architecture, each of your subgraphs uses the Rover CLI to publish its schema to GraphOS: ```mermaid graph LR; @@ -85,7 +85,7 @@ When running your gateway in an environment where outbound traffic to the intern -If you've already set up Apollo Federation without connecting your router to GraphOS, you're probably passing the [`--supergraph` (or `-s`) option](/router/configuration/overview/#-s----supergraph) to the GraphOS Router's startup command: +If you've already set up Apollo Federation without connecting your router to GraphOS, you're probably passing the [`--supergraph` (or `-s`) option](/graphos/reference/router/configuration#-s----supergraph) to the GraphOS Router's startup command: ```sh ./router --config ./router.yaml --supergraph ./your-local-supergraph.graphql @@ -93,7 +93,7 @@ If you've already set up Apollo Federation without connecting your router to Gra The `--supergraph` option applies in scenarios where the router doesn't retrieve the supergraph schema by polling Apollo Uplink. These include: -* **Enabling different deployment environments to refer to a single graph variant**, for example, for [blue-green deployment](./deployment/#example-blue-green-deployment): Use a workflow with the [Platform API](/graphos/platform-api/) to compose and retrieve the supergraph schema for each environment. This enables each environment's router to use the environment's supergraph schema, and then a single graph variant can capture and analyze the operations and traffic of either environment when deployed. +* **Enabling different deployment environments to refer to a single graph variant**, for example, for [blue-green deployment](/federation/managed-federation/deployment/#example-blue-green-deployment): Use a workflow with the [Platform API](/graphos/reference/platform-api/) to compose and retrieve the supergraph schema for each environment. This enables each environment's router to use the environment's supergraph schema, and then a single graph variant can capture and analyze the operations and traffic of either environment when deployed. * **Unmanaged federation**: The Rover CLI composes the supergraph schema and passes the schema's file path to the router via the `--supergraph` option. diff --git a/docs/source/managed-federation/uplink.mdx b/docs/source/managed-federation/uplink.mdx index 3b446df90..025c83453 100644 --- a/docs/source/managed-federation/uplink.mdx +++ b/docs/source/managed-federation/uplink.mdx @@ -4,7 +4,7 @@ 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: +When using [managed federation](/federation/managed-federation/overview/), your supergraph's router by default regularly polls an endpoint called _Apollo Uplink_ for its latest supergraph schema and other configuration: ```mermaid graph LR; @@ -24,7 +24,7 @@ graph LR; class uplink secondary; ``` -If you're using [Enterprise features](/router/enterprise-features/), Uplink also serves your router's [license](/router/enterprise-features/#the-enterprise-license). +If you're using [Enterprise features](https://www.apollographql.com/pricing), Uplink also serves your router's license. To maximize uptime, Uplink is hosted simultaneously at two endpoints, one in GCP and one in AWS: @@ -68,7 +68,7 @@ You can configure the following aspects of your router's Uplink polling behavior You configure Uplink polling for the GraphOS Router by providing certain command-line options when running the router executable. These options all start with `--apollo-uplink`. -[See the GraphOS Router docs](/router/configuration/overview#--apollo-uplink-endpoints). +[See the GraphOS Router docs](/graphos/reference/router/configuration#--apollo-uplink-endpoints). ### `@apollo/gateway` @@ -153,20 +153,20 @@ APOLLO_SCHEMA_CONFIG_DELIVERY_ENDPOINT=https://aws.uplink.api.apollographql.com/ Supergraph schemas provided by Uplink cannot exceed 6MB in size. The vast majority of supergraph schemas are well below this limit. -If your supergraph schema does exceed 6MB, you can set up a [build status webhook](/graphos/metrics/notifications/build-status-notification/) for your graph. Whenever you're notified of a successful supergraph schema composition, your webhook can fetch the latest supergraph schema [via the Rover CLI](/rover/commands/supergraphs#supergraph-fetch). +If your supergraph schema does exceed 6MB, you can set up a [build status webhook](/graphos/platform/insights/notifications/build-status) for your graph. Whenever you're notified of a successful supergraph schema composition, your webhook can fetch the latest supergraph schema [via the Rover CLI](/rover/commands/supergraphs#supergraph-fetch). ## Bypassing Uplink -In advanced use cases, you may want your router to use a supergraph schema different than the latest validated schema provided by Uplink. For example, you have different deployment environments for the same [graph variant](/graphos/graphs/#variants), and you want everything that managed federation provides except for your routers to use supergraph schemas specific to their deployment environment. +In advanced use cases, you may want your router to use a supergraph schema different than the latest validated schema provided by Uplink. For example, you have different deployment environments for the same [graph variant](/graphos/get-started/concepts/graphs-and-variants#variants), and you want everything that managed federation provides except for your routers to use supergraph schemas specific to their deployment environment. -For this scenario, you can follow a workflow that, instead of retrieving supergraph schemas from Uplink, uses the [GraphOS Platform API](/graphos/platform-api) to retrieve a supergraph schema for a specific [GraphOS launch](/graphos/delivery/launches). The workflow, in summary: +For this scenario, you can follow a workflow that, instead of retrieving supergraph schemas from Uplink, uses the [GraphOS Platform API](/graphos/reference/platform-api) to retrieve a supergraph schema for a specific [GraphOS launch](/graphos/platform/schema-management/delivery/launch). The workflow, in summary: 1. When deploying your graphs, publish your subgraphs in a batch using the GraphOS Platform API. * The Platform API triggers a launch (and possible downstream launches for contracts) and returns the launch ID (and downstream launch IDs, if necessary). 1. Poll for the launch status, until the launch (and all downstream launches) has completed successfully. 1. Retrieve the supergraph schema of the successful launch by calling the Platform API with the launch ID. -1. Set or "pin" the supergraph schema to your routers by deploying them with the [`--supergraph` or `-s` option](/router/configuration/overview/#-s----supergraph). +1. Set or "pin" the supergraph schema to your routers by deploying them with the [`--supergraph` or `-s` option](/graphos/reference/router/configuration#-s----supergraph). -For an example with operations calling the Platform API, see a [blue-green deployment example](./deployment/#example-blue-green-deployment). +For an example with operations calling the Platform API, see a [blue-green deployment example](/graphos/schema-design/guides/production-readiness/best-practices#example-blue-green-deployment). diff --git a/docs/source/metrics.mdx b/docs/source/metrics.mdx new file mode 100644 index 000000000..c5d434c93 --- /dev/null +++ b/docs/source/metrics.mdx @@ -0,0 +1,81 @@ +--- +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. + +Your supergraph's router can generate _federated traces_ and [report them to GraphOS](/graphos/metrics/sending-operation-metrics). A federated trace is assembled from timing and error information provided by each subgraph that helps resolve a particular operation. + +## Reporting flow + +The overall flow of a federated trace is as follows: + +1. The router receives an operation from a client. +2. The router generates a [query plan](/federation/query-plans) for the operation and delegates sub-queries to individual subgraphs. +3. Each queried subgraph returns response data to the router. + - The `extensions` field of each response includes trace data for the corresponding sub-query. + - The subgraph must support the federated trace format to include trace data in its response. See [this section](#in-your-subgraphs). +4. The router collects the set of sub-query traces from subgraphs and arranges them in the shape of the query plan. +5. The router [reports the federated trace to GraphOS](/graphos/metrics/sending-operation-metrics/) for processing. + +In summary, subgraphs report timing and error information to the router, and the router is responsible for aggregating those metrics and reporting them to GraphOS. + +## Enabling federated tracing + +### In your subgraphs + +For a subgraph to include trace data in its responses to your router, it must use a subgraph-compatible library that supports the trace format. + +To check whether your subgraph library supports federated tracing, see the `FEDERATED TRACING` entry for the library on [this page](/federation/building-supergraphs/supported-subgraphs/). + +If your library does support federated tracing, see its documentation to learn how to enable the feature. + + + +If your subgraph uses Apollo Server with `@apollo/subgraph`, federated tracing is enabled by default. You can customize this behavior with Apollo Server's [inline trace plugin](/apollo-server/api/plugin/inline-trace). + + + +### In the Apollo Router + +See [Sending Apollo Router usage data to GraphOS](/router/configuration/telemetry/apollo-telemetry). + +### In `@apollo/gateway` + +You can use the `@apollo/server` package's [built-in usage reporting plugin](/apollo-server/api/plugin/usage-reporting) to enable federated tracing for your gateway. Provide an API key to your gateway via the `APOLLO_KEY` environment variable for the gateway to report metrics to the default ingress. To ensure that subgraphs do not report metrics as well, either do not provide them with an `APOLLO_KEY` or install the [`ApolloServerPluginUsageReportingDisabled` plugin](https://www.apollographql.com/docs/apollo-server/api/plugin/usage-reporting/) in your `ApolloServer`. + +These options will cause the Apollo gateway to collect tracing information from the underlying subgraphs and pass them on, along with the query plan, to the Apollo metrics ingress. + + + +By default, metrics are reported to the `current` GraphOS variant. To change the variant for reporting, set the `APOLLO_GRAPH_VARIANT` environment variable. + + + +## How tracing data is exposed from a subgraph + + + +This section explains how your router communicates with subgraphs around encoded tracing information. It is not necessary to understand in order to enable federated tracing. + + + +Your router inspects the `extensions` field of all subgraph responses for the presence of an `ftv1` field. This field contains a representation of the tracing information for the sub-query that was executed against the subgraph, sent as the Base64 encoding of the [protobuf representation](https://github.com/apollographql/apollo-server/blob/main/packages/usage-reporting-protobuf/src/reports.proto) of the trace. + +To obtain this information from a subgraph, the router includes the header pair `'apollo-federation-include-trace': 'ftv1'` in its request (if it's [configured to collect trace data](#in-the-apollo-router)). If the subgraph [supports federated traces](#in-your-subgraphs), it attaches tracing information in the `extensions` field of its response. + +## How traces are constructed and aggregated + +Your router constructs traces in the shape of the [query plan](/federation/query-plans/), embedding an individual `Trace` for each fetch that is performed in the query plan. This indicates the sub-query traces, as well as which order they were fetched from the underlying subgraphs. + +The field-level statistics that Apollo aggregates from these traces are collected for the fields over which the operation was executed in the subgraphs. In other words, field stats are collected based on the operations the query planner makes, instead of the operations that the clients make. On the other hand, operation-level statistics are aggregated over the operations executed by the client, which means that even if query-planning changes, statistics still correspond to the same client-delivered operation. + +## How errors work + +The Apollo Platform provides functionality to modify error details for the client, via the [`formatError`](/apollo-server/data/errors#for-client-responses) option. Additionally, there is functionality to support modifying error details for the metrics ingress, via the [`sendErrors`](/apollo-server/data/errors#for-apollo-studio-reporting) option to the [inline trace plugin](/apollo-server/api/plugin/inline-trace/). + +When modifying errors for the client, you might want to use this option to hide implementation details, like database errors, from your users. When modifying errors for reporting, you might want to obfuscate or redact personal information, like user IDs or emails. + +Since federated metrics collection works by collecting latency and error information from a set of distributed subgraphs, these options are respected from those subgraphs as well as from the router. Subgraphs embed errors in their `ftv1` extension after the `rewriteError` method (passed to the inline trace plugin in the subgraph, not the usage reporting plugin in the gateway!) is applied, and the gateway only reports the errors that are sent via that extension, ignoring the format that downstream errors are reported to end users. This functionality enables subgraph implementers to determine how error information should be displayed to both users and in metrics without needing the gateway to contain any logic that might be subgraph-specific. diff --git a/docs/source/migrating-from-stitching.md b/docs/source/migrating-from-stitching.md index 6f7bf2d19..39d9dddc3 100644 --- a/docs/source/migrating-from-stitching.md +++ b/docs/source/migrating-from-stitching.md @@ -72,7 +72,7 @@ We strongly recommend that you register all of your GraphQL schemas with an [ext [GraphOS](/graphos#whats-in-graphos) provides a free schema registry that helps you manage your federated gateway's configuration. You provide your gateway a Studio API key on startup, which directs the gateway to download your schemas automatically in a fault-tolerant way. -GraphOS can also provide [schema validation](/graphos/delivery/schema-checks/) to ensure that all changes you make to your subgraphs are compatible with your complete graph. +GraphOS can also provide [schema validation](/graphos/platform/schema-management/checks/) to ensure that all changes you make to your subgraphs are compatible with your complete graph. [Learn more about managed configuration.](./managed-federation/overview) diff --git a/docs/source/migrating-from-stitching.mdx b/docs/source/migrating-from-stitching.mdx new file mode 100644 index 000000000..03a8532ee --- /dev/null +++ b/docs/source/migrating-from-stitching.mdx @@ -0,0 +1,188 @@ +--- +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 +steps in this guide to migrate it to use Apollo Federation. + + + +For a real-world example of an organization benefiting from this migration, see [this blog post](https://www.apollographql.com/blog/announcement/expedia-improved-performance-by-moving-from-schema-stitching-to-apollo-federation/). + + + +## Summary of steps + +This guide describes a set of steps for migrating architecture incrementally from stitching to federation. In order to do so, we rely on the fact that changes necessary for federation are completely backwards compatible. Services that implement a part of your graph, also known as _subgraphs_, can be used in both your stitching gateway and your Apollo gateway. + +We recommend that you begin by modifying existing subgraphs in place to support the federation specification while continuing to support schema stitching as well. At this point, you can stand up an Apollo gateway side-by-side with your existing stitching gateway and migrate over the links between the subgraphs in an incremental, backward compatible way. + +Here are the high-level steps for migrating to Apollo Federation: + +1. Add federation support to your subgraphs. +2. Register your GraphQL schemas with a registry. +3. Start up an instance of Apollo Server as a gateway. +4. Migrate stitching logic from your schema-stitching gateway to your subgraphs. +5. Move traffic from the schema-stitching gateway to the Apollo Server gateway. +6. Remove schema-stitching fields from your federated schema and complete your migration. + +Each step is described in detail below. + +[This GitHub repository](https://github.com/apollographql/federation-migration-example) shows the same project before and after migrating to Apollo Federation from schema stitching. + +## Step 1: Add federation support to your subgraphs + +You can add federation support to your subgraphs without impacting your existing schema-stitching architecture. Support for federation is fully compatible with schema stitching. + +Because of this, we recommend that you migrate your subgraphs in-place instead of creating replacement subgraphs. Doing so helps you identify any type conflicts that exist across your graph. + +### Using Apollo Server + +If your subgraphs use Apollo Server, add federation support to them by installing the `@apollo/subgraph` package: + +```bash +npm install @apollo/subgraph +``` + +Then use the `buildSubgraphSchema` function to augment your schema with fields that are necessary for federation support: + +```js +const { ApolloServer } = require('@apollo/server'); +const { buildSubgraphSchema } = require('@apollo/subgraph'); + +const server = new ApolloServer({ + schema: buildSubgraphSchema([ + { + typeDefs, + resolvers, + }, + ]), +}); +``` + +### Using a GraphQL server besides Apollo Server + +There are [several community-contributed packages](/federation/building-supergraphs/supported-subgraphs/) that add federation support to other GraphQL runtimes. + +## Step 2: Register your schemas with a GraphQL registry + +We strongly recommend that you register all of your GraphQL schemas with an [external registry](https://principledgraphql.com/integrity#3-track-the-schema-in-a-registry). This registry supports running the gateway with the subgraphs' partial schemas. Additionally, it enables tracking changes at the subgraph level and protecting the graph from changes that break composition. + +[GraphOS](/graphos#whats-in-graphos) provides a free schema registry that helps you manage your federated gateway's configuration. You provide your gateway a Studio API key on startup, which directs the gateway to download your schemas automatically in a fault-tolerant way. + +GraphOS can also provide [schema validation](/graphos/platform/schema-management/checks/) to ensure that all changes you make to your subgraphs are compatible with your complete graph. + +[Learn more about managed configuration.](/federation/managed-federation/overview) + +## Step 3: Start up an Apollo Server gateway + +After you've registered your schemas, you can start exposing your subgraphs from a federation-compatible gateway. Apollo Server's gateway is a query planner and executor that handles incoming GraphQL requests and breaks them down into a collection of operations to perform on your subgraphs. + +We recommend setting up the Apollo Server gateway alongside your existing schema-stitching gateway. Depending on your infrastructure, you might even want to run both in the same process to support dynamically routing traffic through one gateway or the other. + +To enable managed configuration with GraphOS Studio, set the `APOLLO_KEY` and `APOLLO_GRAPH_REF` environment variables when you start up your Apollo Server gateway, and do not provide the `supergraphSDL` or `serviceList` constructor option to `ApolloGateway`. For details, see the [managed federation documentation](/federation/managed-federation/overview). + +After your gateway is set up, you can make direct queries to it that are routed to the correct subgraphs. + +## Step 4: Move linking logic to your subgraphs + +When using a schema-stitching gateway, your linking logic typically resides in the gateway itself. In the federation model, however, linking logic resides in each subgraph. Therefore, you need to migrate linking logic from your schema-stitching gateway into each of your subgraphs. + +Here are recommendations for common cases when migrating your logic: + +* **Fragments**: Fragments in a schema-stitching resolver, usually translate to a combination of `@key` and `@requires` directives in a federated model. In general, think of `@key` as the field(s) that completely identify an entity, and only use `@requires` for additional, non-identifying information. +* **Filtering types**: We do not recommend filtering types out of your exposed schema when using a gateway. If you want to hide types, do not include them in your subgraph's registered schema. +* **Renaming types**: If you are currently renaming types at the gateway level, rename these types at the subgraph level instead. +* **Transforming fields**: If you are currently transforming fields at the gateway level, transform these fields at the subgraph level instead. + +### Adding resolvers to your subgraphs + +At this point your subgraphs support federation, but they still need to be able to resolve extensions to types that are defined in other subgraphs. + +A schema-stitching architecture declares this logic at the gateway level using the `delegateToSchema` function, like so: + +```js +resolvers: { + Reservation: { + user: { + fragment: `... on Reservation { userId }`, + resolve: (parent, args, context, info) => { + return info.mergeInfo.delegateToSchema({ + schema: userSchema, + operation: 'query', + fieldName: 'user', + args: { + id: parent.userId, + }, + context, + info, + }); + }, + }, + }, +} +``` + +This resolver calls `Query.user` on the `userSchema` to look up a `User`. It adds that user to the `Reservation.user` field that was previously defined at the gateway. This code can all remain. You don't need to remove it from the stitched gateway. In fact, if you did that, the stitched gateway would break. + +On the other hand, a federated architecture defines its resolvers at the subgraph level. These resolvers rely on entities, which are identified by a unique key. For example, the Reservation subgraph must define the `Reservation` type as an entity to allow other subgraphs to extend it. These other subgraphs use the `Reservation`'s `@key` fields to uniquely identify a given instance: + +```graphql +type Reservation @key(fields: "id") { + id: ID! + ... +} +``` + +In the Users subgraph, you can then extend the `Reservation` type with a `user` field like so: + +```graphql +extend type Reservation @key(fields: "id") { + id: ID! @external + userId: ID! @external + user: User @requires(fields: "userId") +} +``` + +The `user` field indicates that it `@requires` a `Reservation`'s `userId` field in order to identify the user that made the reservation. + +Then in the Users subgraph, you can add a resolver for `Reservation.user` like so: + +```js +{ + Reservation: { + user: ({ userId }) => { + return lookupUser(userId); + }, + } +} +``` + +Federated resolvers like this one always receive an object that represents an instance of the extended entity. This object includes the fields that are part of the entity's `@key`, along with any other fields that the resolver `@requires`. + +For example, this `Reservation.user` resolver receives the `id` of the reservation and a `userId`. You can use the `userId` to look up the corresponding user. + +## Step 5: Move traffic from the schema-stitching gateway to the Apollo Server gateway + +At this point, both your schema-stitching gateway and your federated gateway are able to resolve GraphQL operations. You can now begin moving traffic from the schema-stitching gateway to the federated gateway. + +Perform this migration in the manner that best suits your infrastructure and applications. + +Some options include: + +* Testing a complete migration in your staging environment to verify that both gateways behave identically +* Use HTTP headers or feature flags to migrate your internal clients without affecting your user-facing clients + +## Step 6: Remove schema-stitching fields from your federated schema + +After you've fully migrated your graph and incoming traffic to use your federated gateway, you can remove all stitching-specific logic from your architecture. + +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](/federation/) +* [Metrics and analysis of query plans](/federation/performance/monitoring/#metrics-and-observability) +* [Gateway support for live schema updates](/federation/managed-federation/deployment/#the-subgraph-publish-lifecycle) +* [Validation of composition logic and usage traffic](/federation/managed-federation/federated-schema-checks/) diff --git a/docs/source/opentelemetry.mdx b/docs/source/opentelemetry.mdx index ac73b5e9f..7c0f3585c 100644 --- a/docs/source/opentelemetry.mdx +++ b/docs/source/opentelemetry.mdx @@ -11,11 +11,11 @@ You can configure your gateway, your individual subgraphs, or even a monolothic Additionally, the `@apollo/gateway` library provides built-in OpenTelemetry instrumentation to emit [gateway-specific spans](#gateway-specific-spans) for operation traces. -If you are using GraphOS Router, it comes [pre-built with support for OpenTelemetry](/router/configuration/telemetry/overview). +If you are using GraphOS Router, it comes [pre-built with support for OpenTelemetry](/graphos/routing/observability/telemetry). -GraphOS Studio does not currently consume OpenTelemetry-formatted data. To push trace data to Studio, see [Federated trace data](./metrics/). +GraphOS Studio does not currently consume OpenTelemetry-formatted data. To push trace data to Studio, see [Federated trace data](/graphos/routing/observability/federated-trace-data). You should configure OpenTelemetry if you want to push trace data to an OpenTelemetry-compatible system, such as [Zipkin](https://zipkin.io/) or [Jaeger](https://www.jaegertracing.io/). diff --git a/docs/source/performance/monitoring.mdx b/docs/source/performance/monitoring.mdx index 6ac3c534f..230046e4d 100644 --- a/docs/source/performance/monitoring.mdx +++ b/docs/source/performance/monitoring.mdx @@ -13,9 +13,9 @@ This article describes Apollo managed federation features that help you monitor Federated graphs can push operation metrics to GraphOS Studio to enable many powerful tools, including: -* [Operation performance dashboards](/graphos/metrics/operations) -* [Schema checks](/graphos/delivery/schema-checks/) -* [Performance alerts](/graphos/metrics/notifications/performance-alerts) (paid and experimental) +* [Operation performance dashboards](/graphos/platform/insights/operation-metrics) +* [Schema checks](/graphos/platform/schema-management/checks) +* [Performance alerts](/graphos/platform/insights/notifications/performance-alerts) (paid and experimental) With a federated graph, your subgraphs pass _trace data_ (timing and error information for each resolved schema field) to the gateway for every operation. The gateway then pushes that data to Studio: diff --git a/docs/source/query-plans.mdx b/docs/source/query-plans.mdx index aaf61d6b5..7d6340912 100644 --- a/docs/source/query-plans.mdx +++ b/docs/source/query-plans.mdx @@ -4,20 +4,7 @@ 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. - -Whenever your router receives an incoming GraphQL operation, it needs to figure out how to use your subgraphs to populate data for each of that operation's fields. To do this, the router generates a _query plan_: - -```mermaid -flowchart TB; - parallel(Parallel); - parallel --> fetchReviews("Fetch (reviews)"); - parallel --> fetchUsers("Fetch (users)"); - fetchReviews --> subFetchHotels("Fetch (hotels)"); - subFetchHotels --> flatten("Flatten (latestReviews,[],hotel)") -``` - -A query plan is a blueprint for dividing a single incoming operation into one or more operations that are each resolvable by a single subgraph. Some of these operations depend on the results of other operations, so the query plan also defines any required ordering for their execution. +Learn more about query plans to help you optimize and debug advanced use cases of Apollo Federation. ## Example graph @@ -267,7 +254,7 @@ Sequence { } ``` -This node appears in query plans whenever one subgraph's response depends on data that first must be returned by another subgraph. This occurs most commonly when a query requests fields of an [entity](./entities/) that are defined across multiple subgraphs. +This node appears in query plans whenever one subgraph's response depends on data that first must be returned by another subgraph. This occurs most commonly when a query requests fields of an [entity](/graphos/get-started/guides/federate-schemas#entity-overview) that are defined across multiple subgraphs. As an example, we can return to the `GetHotels` query from our [example graph](#example-graph): @@ -432,10 +419,10 @@ Flatten(path: "hotels.@") { Instead of containing a GraphQL operation, this `Fetch` node contains two GraphQL fragments, separated by `=>`. -- 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 first fragment is a representation of the entity being resolved (in this case, `Hotel`). [Learn more about entity representations](/graphos/get-started/guides/federate-schemas/#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](./building-supergraphs/subgraphs-overview/#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](/graphos/reference/federation/subgraph-specific-fields/#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. @@ -445,7 +432,7 @@ A `Defer` node corresponds to one or more `@defer`s at the same level of nesting The node contains a _primary block_ and an array of _deferred blocks_. The primary block represents the part of the query that isn't deferred. Each deferred block corresponds to the one deferred part of the query. -Read more about how `@defer` works in the [router support for @defer article](/router/executing-operations/defer-support/). +Read more about how `@defer` works in the [router support for @defer article](/graphos/routing/operations/defer/). ```graphql QueryPlan { @@ -496,13 +483,13 @@ QueryPlan { You can view the query plan for a particular operation in any of the following ways: -- [In the GraphOS Studio Explorer](/graphos/explorer/additional-features#query-plans-for-supergraphs) - - Note that you must [register your federated graph](./managed-federation/setup/) with GraphOS to view query plans in the Explorer. +- [In the GraphOS Studio Explorer](/graphos/platform/explorer/additional-features#query-plans-for-supergraphs) + - Note that you must publish your graph to GraphOS to view query plans in the Explorer. - As direct output from the `@apollo/gateway` library (see below) ### Outputting query plans with headers -With [the Apollo Router Core](/router/) v0.16.0+ and [`@apollo/gateway`](/apollo-server/using-federation/api/apollo-gateway/) v2.5.4+, you can pass the following headers to return the query plans in the GraphQL response extensions: +With [the Apollo Router Core](https://github.com/apollographql/router) v0.16.0+ and [`@apollo/gateway`](/apollo-server/using-federation/api/apollo-gateway/) v2.5.4+, you can pass the following headers to return the query plans in the GraphQL response extensions: - Including the `Apollo-Query-Plan-Experimental` header returns the query plan in the response extensions - Additionally including the `Apollo-Query-Plan-Experimental-Format` header with one of the supported options changes the output format: diff --git a/docs/source/quickstart.mdx b/docs/source/quickstart.mdx deleted file mode 100644 index 2de402fe8..000000000 --- a/docs/source/quickstart.mdx +++ /dev/null @@ -1,609 +0,0 @@ ---- -title: Apollo GraphOS Quickstart -subtitle: Build a federated GraphQL API with Apollo Federation and GraphOS -description: Build a federated GraphQL API with Apollo Federation and GraphOS ---- - -Apollo Federation combines microservices into a single GraphQL API, providing real-time access to all your data sources for all your client applications. Apollo GraphOS is the platform for building, testing, and deploying a federated GraphQL APIβ€”also known as a supergraph. - -```mermaid -graph LR; - web(Web
client); - mobile(Mobile
client); - iot(IoT
client); - subgraph Supergraph; - router([Federated
GraphQL API]); - serviceA[Products
service]; - serviceB[Users
service]; - serviceC[Inventory
service]; - router --- serviceA & serviceB & serviceC; - end; - web -.- router; - mobile -.- router; - iot -.- router; - class web secondary; - class mobile secondary; - class iot secondary; -``` - -By the end of this quickstart, you'll have set up a supergraph that integrates data from products, users, and inventory services. -Along the way, you'll learn about tools like the Rover CLI and GraphOS Studio. - -To learn more about Apollo Federation and the benefits of using it with GraphOS, check out these resources: - -- [Introduction to Apollo Federation](./) -- [Introduction to GraphOS](/graphos) - - - -## Prerequisites - -To complete this quickstart, you must have the following: - -- A local version of Apollo's retail demo - - Download or clone it from its [GitHub repository](https://github.com/apollosolutions/retail-supergraph) -- The latest LTS version of [Node.js](https://nodejs.org/en) - - - - While the retail demo uses Node.js for all its services, Apollo Federation is compatible with [many GraphQL server libraries](./building-supergraphs/compatible-subgraphs). - You can also federate services that use different programming languages and different server libraries. - - - -If you haven't already, set these up before continuing. - -## Overview - -Setting up a supergraph with GraphOS takes a few steps: - -1. Install the Rover CLI. -2. Start local development. -3. Publish your servicesβ€”known as _subgraphs_ in the context of a supergraphβ€”to GraphOS. - -Once you've published your subgraphs, you can use GraphOS Studio to explore and better understand your supergraph. - -### Step 1. Install the Rover CLI - -_Rover_ is Apollo's CLI for managing all kinds of graphs, including subgraphs and supergraphs. You'll use it throughout this quickstart. - - - -Even if you already have Rover installed, update your version by completing this step. - - - -Install the latest Rover release with the appropriate command for your system: - -```sh title="MacOS / Unix-like" showLineNumbers=false -curl -sSL https://rover.apollo.dev/nix/latest | sh -``` - -```sh title="Windows" showLineNumbers=false -iwr 'https://rover.apollo.dev/win/latest' | iex -``` - -After installing, run `rover -V` in your terminal to confirm it installed successfully. -Verify that the printed version number matches the [latest release](https://github.com/apollographql/rover/releases). -If it doesn't, you might need to manually delete an outdated installation. - -Now that you've installed Rover, you're ready to start local development with your supergraph! - -### Step 2. Start local development - -Running a supergraph entails running its _router_. -The router is the single access point to your supergraph for clients. -The router receives incoming operations and intelligently routes them across component services before returning a unified response. - -```mermaid -graph LR; - clients(Clients); - subgraph Supergraph; - router([Router]); - serviceA[Products
subgraph]; - serviceB[Users
subgraph]; - serviceC[Inventory
subgraph]; - router --- serviceA & serviceB & serviceC; - end; - clients -.- router; - class clients secondary; -``` - -In this step, you'll do the following: - -1. Locally run the subgraphs. -2. Locally run your router. -3. Query your router to ensure it's working as expected. - -#### Run subgraphs - -To start local development, you must first get the subgraphs in the [retail demo](https://github.com/apollosolutions/retail-supergraph) up and running. -From the root directory, install dependencies: - -```sh showLineNumbers=false -npm install -``` - -Then run the subgraphs: - -```sh showLineNumbers=false -npm run dev:subgraphs -``` - -In your terminal, you should see notifications for each subgraph: - -```sh showLineNumbers=false disableCopy=true -Setting up [products] subgraph at http://localhost:4001/products/graphql -Setting up [orders] subgraph at http://localhost:4001/orders/graphql -Setting up [users] subgraph at http://localhost:4001/users/graphql -... -``` - -Keep these subgraphs up and running so that the router can query them. - - - -The retail demo contains the code behind each of these subgraphs, including their schemas, resolvers, and mock data. -These files are provided for your referenceβ€”understanding them isn't necessary to complete this quickstart. -Check out these tutorials to learn more about [GraphQL schemas](https://www.apollographql.com/tutorials/lift-off-part1) and [resolvers](https://www.apollographql.com/tutorials/lift-off-part2). - - - -#### Run router - -With your subgraphs running, you can use Rover to start the router locally. -To do so, use the `rover dev` command with the `--supergraph-config` and `--router-config` options. - -The retail demo comes with `supergraph-config-dev.yaml` and `router-config-dev.yaml` YAML configuration files that include subgraph names, URLs, and router configurations. - -In a **different terminal window** from the one where the subgraphs are running, run this command: - -```sh showLineNumbers=false -rover dev \ - --supergraph-config supergraph-config-dev.yaml \ - --router-config router-config-dev.yaml -``` - -When you first start the `rover dev` process, you'll see the following happening in the terminal: - -- Rover obtains the provided subgraph schemas and starts sessions for each of them. - - ```sh showLineNumbers=false - πŸ›« starting a session with the 'discovery' subgraph - πŸ›« starting a session with the 'checkout' subgraph - πŸ›« starting a session with the 'users' subgraph - πŸ›« starting a session with the 'inventory' subgraph - πŸ›« starting a session with the 'orders' subgraph - πŸ›« starting a session with the 'shipping' subgraph - πŸ›« starting a session with the 'products' subgraph - πŸ›« starting a session with the 'reviews' subgraph - ``` - -- Rover uses Apollo Federation to compose a supergraph schema by adding subgraph schemas one at a time. - - ```sh showLineNumbers=false - 🎢 composing supergraph with Federation v2.8.0 - βœ… successfully composed after adding the 'products' subgraph - ``` - - - The order in which Rover adds subgraphs is undefined, so you might see composition errors like the following during intermediate steps. - - ```sh showLineNumbers=false - error[E029]: Encountered 1 build error while trying to build a supergraph. - ``` - -- When composition completes successfully, Rover starts a locally running router session and provides it with the supergraph schema. - - ```sh showLineNumbers=false - πŸš€ your supergraph is running! head to http://localhost:4000 to query your supergraph - ``` - - - - This message may be followed by composition errors and successful composition notifications. As long as you can access http://localhost:4000, your router is running locally. - - - -- Rover starts watching the provided subgraph schemas for changes. - - ```sh showLineNumbers=false - πŸ‘€ watching ./subgraphs/products/schema.graphql for changes - ``` - - - Rover recomposes the supergraph schema whenever it detects one. Recomposition automatically reloads the router. - -Nice! You've now got a supergraph running locally. - -#### Query your router - -To ensure everything works as expected, you can query your router in the Apollo Sandbox that Rover automatically starts up. - -1. Open [localhost:4000](http://localhost:4000/) in a browser to access your locally running router. It should look something like this: - - The Apollo Sandbox with a prepopulated example query. - -2. Run the following query by copying and pasting it into the **Operation** window and then clicking the play button labeled **ExampleQuery**. - -```graphQL showLineNumbers=false -query ExampleQuery { - listAllProducts { - id - title - description - mediaUrl - variants { - id - price - } - } -} -``` - -3. Confirm that once you run the operation, you see the following in the **Response** panel on the right: - - - - ```JSON showLineNumbers=false disableCopy=true - { - "data": { - "listAllProducts": [ - { - "id": "product:1", - "title": "Air Jordan 1 Mid", - "description": "Air Jordan 1 Mid is a blue, grey and white sneaker from the iconic jordan brand", - "mediaUrl": "https://sneakernews.com/wp-content/uploads/2022/06/air-jordan-1-mid-university-blue-grey-dx9276-100-6.jpg", - "variants": [ - { - "id": "variant:1", - "price": 600.25 - }, - { - "id": "variant:2", - "price": 20.12 - } - ] - }, - { - "id": "product:2", - "title": "Supreme x Tiffany & Co. Box Logo Tee", - "description": "A classic Supreme vbox t-shirt in the signature Tiffany blue.", - "mediaUrl": "https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcQWDHD3SSS98UAVKODaql7nrDTopfL4tcTnEltW8Yqy4hyDu4i5b70Wb3Y8-wACJIo5g-ZdRULPQKUmt7JfwiaSdgiOBz4pvU_YelKHUI4nhoXmMJPeh_tyWQ", - "variants": [ - { - "id": "variant:4", - "price": 600.25 - }, - { - "id": "variant:5", - "price": 600.25 - }, - { - "id": "variant:6", - "price": 600.25 - }, - { - "id": "variant:7", - "price": 600.25 - }, - { - "id": "variant:8", - "price": 600.25 - } - ] - }, - { - "id": "product:3", - "title": "THE MACKINAC 40MM", - "description": "Established by Detroit’s historic Bayview Yacht club, the days-long Port Huron to Mackinac Island regatta is one of the longest and most grueling freshwater races in the world.\n\nNamed for this legendary competition, the Shinola Mackinac is our first watch with automatic, single-eye chronograph yacht-timer functionality.\n\nIt’s a precision instrument designed to be passed on for generationsβ€”just like the tradition that inspires it.", - "mediaUrl": "https://shinola-m2.imgix.net/images/Products/20253783-sdt-012455107/S0120253783_F2_MAIN_01.png?h=1500&w=1500&bg=f7f7f7&auto=format,compress&fit=fillmax", - "variants": [ - { - "id": "variant:9", - "price": 3499.99 - } - ] - }, - ] - }, - ... - } - ``` - - - - This operation requests a list of all products from the products subgraph. - You can remove fields like `mediaUrl` or add fields like `releaseDate` to the operation to see how the reponse changes. - - Next, you'll execute an operation that demonstrates the power of federation. - -4. Replace the example query in the **Operation** window with the following. Run it by clicking the play button, now labeled **GetCart**. - - ```graphql showLineNumbers=false - # Get the current user's cart with all the items and their product info as well as the price. - query GetCart { - user { - id - username - shippingAddress - cart { - subtotal - items { - price - inventory { - inStock - } - product { - title - description - mediaUrl - } - } - } - } - } - ``` - -5. In the **Response** panel, you should see an error like this: `Could not locate user by id. Please specify a valid x-user-id header like user:1`. - - This error appears because the operation retrieves a particular user's shopping cart _given the user's ID_. The operation expects the user ID to be in the request header. You can include it in the request headers in Sandbox by doing the following: - - - Open the **Headers** tab below the **Operation** editor. - - Click **+ New header**. - - Enter `x-user-id` as the **header key** and `user:1` as the **value**. - - The GraphOS Studio Explorer with a GetCart operation and headers. - -6. Rerun the request. In the **Response** panel, confirm you see the following: - - - - ```JSON showLineNumbers=false disableCopy=true - { - "data": { - "user": { - "id": "user:1", - "username": "User One", - "shippingAddress": "123 Main St", - "cart": { - "subtotal": 620.37, - "items": [ - { - "price": 20.12, - "inventory": { - "inStock": true - }, - "product": { - "title": "Air Jordan 1 Mid", - "description": "Air Jordan 1 Mid is a blue, grey and white sneaker from the iconic jordan brand", - "mediaUrl": "https://sneakernews.com/wp-content/uploads/2022/06/air-jordan-1-mid-university-blue-grey-dx9276-100-6.jpg" - } - }, - { - "price": 600.25, - "inventory": { - "inStock": true - }, - "product": { - "title": "Supreme x Tiffany & Co. Box Logo Tee", - "description": "A classic Supreme vbox t-shirt in the signature Tiffany blue.", - "mediaUrl": "https://encrypted-tbn2.gstatic.com/shopping?q=tbn:ANd9GcQWDHD3SSS98UAVKODaql7nrDTopfL4tcTnEltW8Yqy4hyDu4i5b70Wb3Y8-wACJIo5g-ZdRULPQKUmt7JfwiaSdgiOBz4pvU_YelKHUI4nhoXmMJPeh_tyWQ" - } - } - ] - } - } - } - } - ``` - - $600.25! That must be some t-shirt! - - - -Excellent! You've used _one_ request to your router to get data from across different services. -In the last part of this local development step, you'll learn more about how the router accomplished this. - -#### Inspect query plans - -The `GetCart` operation is powerful because it gathers data across various subgraphs: `users`, `products`, `inventory`, and more. -Sandbox displays an operation's **Query Plan** to help you understand how the router intelligently orchestrates subrequests to these subgraphs. - -A query plan is a blueprint for dividing a single incoming operation into one or more operations that are each resolvable by a single subgraph. -You can view the query plan instead of the response by clicking **Response** and selecting **Query Plan**. - -Apollo Sandbox shows a query plan diagram for an operation. - -Query plans are a powerful tool for understanding operations, whether they're run locally or from client applications. - -In the last step of this tutorial, you'll publish your locally running subgraph schemas to GraphOS Studio to learn more about your supergraph. - -### Step 3. Publish your subgraphs - -To create a supergraph, you individually publish each subgraph schema to GraphOS. -Whenever you publish a subgraph schema, GraphOS attempts to compose all the latest subgraph schemas into a single supergraph schema. -If this composition succeeds, GraphOS updates your router with the result. - -In this step, you'll create an empty supergraph in GraphOS Studio and then publish subgraph schemas to it using Rover. - -#### Create supergraph - -1. If you don't yet have a [GraphOS Studio](https://studio.apollographql.com/?referrer=docs-content) account, create one now. -2. If you're starting from a new Studio account, click **Connect a GraphQL API** when prompted. If working from an existing Studio account, click **+ Create New Graph** on the top right of the page. -3. Enter a **Graph title**, for example `Federation Quickstart`. Leave the **Graph Architecture** as `Supergraph (Default)` and **Visible to Team Members** as `On`. Click **Next**. -4. A **Publish your schema using Federation** dialog appears. Copy the entire example code block to a local text file using the copy button. - - A dialog from GraphOS Studio displays a hidden API key and graph ref. - - It should look something like this: - - ```sh showLineNumbers=false disableCopy=true - APOLLO_KEY=service:Federation-Quickstart:β€’β€’β€’β€’β€’β€’β€’β€’β€’β€’β€’β€’β€’β€’β€’β€’β€’β€’β€’β€’β€’ \ - rover subgraph publish Federation-Quickstart@current \ - --schema ./products-schema.graphql \ - --name your-subgraph-name \ - --routing-url http://products.prod.svc.cluster.local:4001/graphql - ``` - - - The protected value that appears after `APOLLO_KEY=` and begins with `service:` is your graph API key. - - The value that appears after `rover subgraph publish` is your graph ref. By default, it ends with `@current`. - - You'll use both your graph API key and graph ref in the next step. - - - - API keys are secret credentials. Never share them outside your organization or commit them to version control. Delete and replace API keys that you believe are compromised. - - - -5. Leave the dialog open; you'll complete setup with Rover. - -#### Publish subgraph schemas - -Complete the next steps back in your terminal: - -1. Ensure your subgraphs are still [running locally](#run-subgraphs). -2. Take the multi-line command you copied from Studio and replace the last three lines with the following: - - ```sh showLineNumbers=false - --schema ./subgraphs/products/schema.graphql \ - --name products \ - --routing-url http://localhost:4001/products/graphql - ``` - - It should now look something like this: - - ```sh showLineNumbers=false disableCopy - APOLLO_KEY=service: \ - rover subgraph publish \ - --schema ./subgraphs/products/schema.graphql \ - --name products \ - --routing-url http://localhost:4001/products/graphql - ``` - - - The `--schema` option specifies the path to the schema file to publish. - - The `--name` option specifies the name of the subgraph. - - The `--routing-url` is the address the router should send subrequests for this particular subgraph to. - - - - In a production supergraph, a subgraph's `routing-url` is generally its public endpoint. - - - -2. While still in the retail demo's root directory, open a new terminal window. Paste and run your updated multi-line command. - - Because the command provides a `localhost` address for the `routing-url`, the terminal will confirm that you want to publish. Enter `Y`. - - If the command is successful, you'll see the following in your terminal: - - ```sh showLineNumbers=false disableCopy=true - A new subgraph called 'products' was created in - The supergraph schema for was updated, - composed from the updated 'products' subgraph - ``` - - - After a few moments, the GraphOS Studio dialog you left open when creating an empty supergraph will show **Schema published** on the bottom left. - - A dialog from GraphOS Studio updates to show a schema has been published. - -3. Run the `rover subgraph publish` command for the `inventory` subgraph, substituting your graph ref. You no longer need to include the first line containing your graph API key: - - ```sh showLineNumbers=false - rover subgraph publish \ - --schema ./subgraphs/inventory/schema.graphql \ - --name inventory \ - --routing-url http://localhost:4001/inventory/graphql - -4. Do the same for the `users` subgraph, substituting your graph ref: - - ```sh showLineNumbers=false - rover subgraph publish \ - --schema ./subgraphs/users/schema.graphql \ - --name users \ - --routing-url http://localhost:4001/users/graphql - -Congrats! With these subgraphs published, you can explore and interact with them and the supergraph composed of them in GraphOS Studio. - - - -The retail demo contains other subgraphsβ€”for example, the `reviews` and `shipping` subgraphs. -The three you've just published are enough to understand what GraphOS Studio has to offer, but you can publish the others if you want to explore their schemas. - - - -## Explore your supergraph - -Once you've published subgraphs, open the **Schema** page from the left nav in [Studio](https://studio.apollographql.com/?referrer=docs-content) to explore the composed supergraph schema as well as individual subgraph schemas and the relationships between them. - - - The **Reference** tab lets you view and filter your schema's type and field definitions. For example, select **Objects**, then **User**, to see all of the `user` type's fields and which subgraphs provide them. - - The GraphOS Studio Schema Reference page shows filterable list of types and fields. - - - The **SDL** tab displays your supergraph's API schema and supergraph schema, filterable by subgraph. Viewing the supergraph SDL (Schema Definition Language) allows developers to see exactly how subgraph schemas are composed together. - - The GraphOS Studio Schema SDL page has a left nav listing all subgraphs. - - - The **Visualization** tab provides a filterable, navigable, graphical representation of your supergraph schema. Once you start collecting metrics on your supergraph, you can use the visualization tool to create heatmaps to identify fields that are most frequently used, or have the highest latency or errors. - - The GraphOS Studio Schema Visualization page shows an interactive representation of an e-commerce supergraph schema including Orders, Users, Variants, Products, etc. - -GraphOS also offers tools for managing your schema, including schema proposals, checks, and linting. Additionally, GraphOS schema delivery tools help you integrate schema publication into your DevOps workflows. - -Once you deploy your router, either by self-hosting it or using the Apollo-managed cloud option, you can use it to collect and export telemetry to GraphOS Studio and other observability and application performance monitoring (APM) tools. - -## Next steps - -Depending on your goals, you have several options for learning more about GraphOS' capabilities or moving your supergraph closer to production: - -- Learn about the different [router types](/graphos/routing) to decide which type best fits your use case. -- Learn more about Studio features, including [proposals](/graphos/delivery/schema-proposals), [linting](/graphos/delivery/schema-linter), and [checks](/graphos/delivery/schema-checks). - - If you'd like a visual tour of some of these features, check out the video below. - - - - - - -- Learn about GraphOS [metrics](/graphos/metrics) and [router telemetry](/router/configuration/telemetry/overview/). -- Check out the [`rover template` command](/rover/commands/template) to quickly start a new GraphQL project or explore implementations in different libraries and languages. \ No newline at end of file diff --git a/docs/source/subgraph-spec.mdx b/docs/source/subgraph-spec.mdx index 7eb9d49e3..f0c590ac1 100644 --- a/docs/source/subgraph-spec.mdx +++ b/docs/source/subgraph-spec.mdx @@ -4,7 +4,7 @@ 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/compatible-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](/graphos/reference/federation/compatible-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). @@ -105,7 +105,7 @@ Apollo strongly recommends against dynamic composition in the graph router. Dyna The "enhanced" introspection query above differs from [the GraphQL spec's built-in introspection query](https://spec.graphql.org/October2021/#sec-Schema-Introspection) in the following ways: - The returned schema representation is a string instead of a `__Schema` object. -- The returned schema string includes all uses of [federation-specific directives](./federated-schemas/federated-directives/), such as `@key`. +- The returned schema string includes all uses of [federation-specific directives](/graphos/reference/federation/directives/), such as `@key`. - The built-in introspection query's response does not include the uses of any directives. - The graph router requires these federation-specific directives to perform composition successfully. - If a subgraph server "disables introspection", the enhanced introspection query is still available. @@ -412,7 +412,7 @@ Your subgraph library does not need to use this reference resolver pattern. It j This section describes type and field definitions that a valid subgraph service must automatically add to its schema. These definitions are all listed above in [Subgraph schema additions](#subgraph-schema-additions). -For descriptions of added directives, see [Federation-specific GraphQL directives](./federated-schemas/federated-directives/). +For descriptions of added directives, see [Federation-specific GraphQL directives](/graphos/reference/federation/directives/). ### `Query` fields @@ -488,4 +488,4 @@ This string-serialized scalar represents an authorization policy. ### Directives -See [Federation-specific GraphQL directives](./federated-schemas/federated-directives/). +See [Federation-specific GraphQL directives](/graphos/reference/federation/directives/).
* To define a value type with shared fields across multiple subgraphs, those shared fields must be marked as `@shareable` in every subgraph that defines them. -* Value type fields can differ across subgraphs (in certain ways). For details, see [Differing shared fields](./federated-schemas/sharing-types#differing-shared-fields). +* Value type fields can differ across subgraphs (in certain ways). For details, see [Differing shared fields](/graphos/schema-design/federated-schemas/sharing-types#differing-shared-fields).