From ee43f1b4bad2aef08fc4537a1d1daf37a8c394a7 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Thu, 20 Mar 2025 14:23:45 -0600 Subject: [PATCH 1/4] Mirror docs IA --- .../federated-schemas/reference}/backward-compatibility.mdx | 0 .../federated-schemas/reference}/compatible-subgraphs.mdx | 0 .../federated-schemas/reference}/composition-rules.mdx | 0 .../federated-schemas/reference}/directives.mdx | 0 .../federated-schemas/reference}/errors.mdx | 0 .../federated-schemas/reference}/hints.mdx | 0 .../federated-schemas/reference}/moving-to-federation-2.mdx | 0 .../federated-schemas/reference}/query-plans.mdx | 0 .../federated-schemas/reference}/subgraph-spec.mdx | 0 .../federated-schemas/reference}/subgraph-specific-fields.mdx | 0 .../federated-schemas/reference}/versions.mdx | 0 11 files changed, 0 insertions(+), 0 deletions(-) rename docs/source/{reference/migration => schema-design/federated-schemas/reference}/backward-compatibility.mdx (100%) rename docs/source/{reference/federation => schema-design/federated-schemas/reference}/compatible-subgraphs.mdx (100%) rename docs/source/{reference/federation => schema-design/federated-schemas/reference}/composition-rules.mdx (100%) rename docs/source/{reference/federation => schema-design/federated-schemas/reference}/directives.mdx (100%) rename docs/source/{reference/federation => schema-design/federated-schemas/reference}/errors.mdx (100%) rename docs/source/{reference/federation => schema-design/federated-schemas/reference}/hints.mdx (100%) rename docs/source/{reference/migration => schema-design/federated-schemas/reference}/moving-to-federation-2.mdx (100%) rename docs/source/{reference/federation => schema-design/federated-schemas/reference}/query-plans.mdx (100%) rename docs/source/{reference/federation => schema-design/federated-schemas/reference}/subgraph-spec.mdx (100%) rename docs/source/{reference/federation => schema-design/federated-schemas/reference}/subgraph-specific-fields.mdx (100%) rename docs/source/{reference/federation => schema-design/federated-schemas/reference}/versions.mdx (100%) diff --git a/docs/source/reference/migration/backward-compatibility.mdx b/docs/source/schema-design/federated-schemas/reference/backward-compatibility.mdx similarity index 100% rename from docs/source/reference/migration/backward-compatibility.mdx rename to docs/source/schema-design/federated-schemas/reference/backward-compatibility.mdx diff --git a/docs/source/reference/federation/compatible-subgraphs.mdx b/docs/source/schema-design/federated-schemas/reference/compatible-subgraphs.mdx similarity index 100% rename from docs/source/reference/federation/compatible-subgraphs.mdx rename to docs/source/schema-design/federated-schemas/reference/compatible-subgraphs.mdx diff --git a/docs/source/reference/federation/composition-rules.mdx b/docs/source/schema-design/federated-schemas/reference/composition-rules.mdx similarity index 100% rename from docs/source/reference/federation/composition-rules.mdx rename to docs/source/schema-design/federated-schemas/reference/composition-rules.mdx diff --git a/docs/source/reference/federation/directives.mdx b/docs/source/schema-design/federated-schemas/reference/directives.mdx similarity index 100% rename from docs/source/reference/federation/directives.mdx rename to docs/source/schema-design/federated-schemas/reference/directives.mdx diff --git a/docs/source/reference/federation/errors.mdx b/docs/source/schema-design/federated-schemas/reference/errors.mdx similarity index 100% rename from docs/source/reference/federation/errors.mdx rename to docs/source/schema-design/federated-schemas/reference/errors.mdx diff --git a/docs/source/reference/federation/hints.mdx b/docs/source/schema-design/federated-schemas/reference/hints.mdx similarity index 100% rename from docs/source/reference/federation/hints.mdx rename to docs/source/schema-design/federated-schemas/reference/hints.mdx diff --git a/docs/source/reference/migration/moving-to-federation-2.mdx b/docs/source/schema-design/federated-schemas/reference/moving-to-federation-2.mdx similarity index 100% rename from docs/source/reference/migration/moving-to-federation-2.mdx rename to docs/source/schema-design/federated-schemas/reference/moving-to-federation-2.mdx diff --git a/docs/source/reference/federation/query-plans.mdx b/docs/source/schema-design/federated-schemas/reference/query-plans.mdx similarity index 100% rename from docs/source/reference/federation/query-plans.mdx rename to docs/source/schema-design/federated-schemas/reference/query-plans.mdx diff --git a/docs/source/reference/federation/subgraph-spec.mdx b/docs/source/schema-design/federated-schemas/reference/subgraph-spec.mdx similarity index 100% rename from docs/source/reference/federation/subgraph-spec.mdx rename to docs/source/schema-design/federated-schemas/reference/subgraph-spec.mdx diff --git a/docs/source/reference/federation/subgraph-specific-fields.mdx b/docs/source/schema-design/federated-schemas/reference/subgraph-specific-fields.mdx similarity index 100% rename from docs/source/reference/federation/subgraph-specific-fields.mdx rename to docs/source/schema-design/federated-schemas/reference/subgraph-specific-fields.mdx diff --git a/docs/source/reference/federation/versions.mdx b/docs/source/schema-design/federated-schemas/reference/versions.mdx similarity index 100% rename from docs/source/reference/federation/versions.mdx rename to docs/source/schema-design/federated-schemas/reference/versions.mdx From 3313ca2dc02224c708903ca973c55fead27ec065 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Thu, 20 Mar 2025 14:37:11 -0600 Subject: [PATCH 2/4] Update relative links --- .../federated-schemas/reference/directives.mdx | 6 +++--- .../federated-schemas/reference/moving-to-federation-2.mdx | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/source/schema-design/federated-schemas/reference/directives.mdx b/docs/source/schema-design/federated-schemas/reference/directives.mdx index ba4d4e6a5..ea4cd21ba 100644 --- a/docs/source/schema-design/federated-schemas/reference/directives.mdx +++ b/docs/source/schema-design/federated-schemas/reference/directives.mdx @@ -4,9 +4,9 @@ subtitle: Reference for Apollo Federation specific GraphQL directives description: Reference for GraphQL federation directives including @key, @extends, @sharable, @override, @requires and more. --- -import ProgressiveOverrideEnterprise from '../../../shared/progressive-override-enterprise.mdx'; -import EnterpriseDirective from '../../../shared/enterprise-directive.mdx'; -import LinkDirective from '../../../shared/link-directive.mdx'; +import ProgressiveOverrideEnterprise from '../../../../shared/progressive-override-enterprise.mdx'; +import EnterpriseDirective from '../../../../shared/enterprise-directive.mdx'; +import LinkDirective from '../../../../shared/link-directive.mdx'; Apollo Federation defines a collection of directives that you use in your subgraph schemas to enable certain features. diff --git a/docs/source/schema-design/federated-schemas/reference/moving-to-federation-2.mdx b/docs/source/schema-design/federated-schemas/reference/moving-to-federation-2.mdx index 0875a417b..be1e2ad5f 100644 --- a/docs/source/schema-design/federated-schemas/reference/moving-to-federation-2.mdx +++ b/docs/source/schema-design/federated-schemas/reference/moving-to-federation-2.mdx @@ -88,13 +88,13 @@ Open the Settings page for the variant you want to move to Federation 2, then se Edit variant settings in Studio Click **Edit Configuration**. The following dialog appears: -Edit supported directives in Studio +Edit supported directives in Studio In the Federation Version dropdown, select **Federation 2** and click **Save**. From f39b4bef55aabf6c9b64a3b6d37de4878a1e0cfb Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Thu, 20 Mar 2025 14:44:12 -0600 Subject: [PATCH 3/4] Update relative link --- .../schema-design/federated-schemas/reference/subgraph-spec.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/schema-design/federated-schemas/reference/subgraph-spec.mdx b/docs/source/schema-design/federated-schemas/reference/subgraph-spec.mdx index 4d0d853a1..dd076167d 100644 --- a/docs/source/schema-design/federated-schemas/reference/subgraph-spec.mdx +++ b/docs/source/schema-design/federated-schemas/reference/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. --- -import LinkDirective from '../../../shared/link-directive.mdx'; +import LinkDirective from '../../../../shared/link-directive.mdx'; 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. From 8c97331aef11524e7b1ee21ab199bb41569693e6 Mon Sep 17 00:00:00 2001 From: Maria Elisabeth Schreiber Date: Thu, 20 Mar 2025 14:52:59 -0600 Subject: [PATCH 4/4] Move migration guides --- .../reference/migration/from-monolith.mdx | 281 ------------------ .../migration/migrating-from-stitching.mdx | 188 ------------ 2 files changed, 469 deletions(-) delete mode 100644 docs/source/reference/migration/from-monolith.mdx delete mode 100644 docs/source/reference/migration/migrating-from-stitching.mdx diff --git a/docs/source/reference/migration/from-monolith.mdx b/docs/source/reference/migration/from-monolith.mdx deleted file mode 100644 index d82b12b74..000000000 --- a/docs/source/reference/migration/from-monolith.mdx +++ /dev/null @@ -1,281 +0,0 @@ ---- -title: Moving a GraphQL Monolith to Apollo Federation -subtitle: Steps for migrating from a GraphQL monolith to a federated supergraph -description: A step-by-step guide for migrating from a GraphQL monolith to a federated supergraph with Apollo Federation. -published: 2022-09-06 -id: TN0013 -tags: [federation, server] -redirectFrom: - - /technotes/TN0013-monolith-to-federation/ ---- - - - -For a complete, step-by-step tutorial, check out [Voyage II: Federating the monolith](https://www.apollographql.com/tutorials/voyage-part2). - - - -As with any monolithic service, teams can struggle to change and maintain their GraphQL API as it grows larger and receives contributions from more developers. - -Breaking up the monolith into smaller GraphQL APIs might be the right strategy for your team. With Apollo Federation, you can break up a monolith without sacrificing the unified API that your client applications depend on. Each _subgraph_ can be independently updated, deployed, and scaled while contributing to a single unified schema. - -Here are the steps we recommend to convert a monolithic GraphQL API into a federated GraphQL API. - -## Planning and preparation - -### 1. Put a router in front of your existing API - -Start the process by making a "federated graph of one." Your existing monolith can act as a subgraph without any schema changes. - -1. If you're not already publishing your schema to GraphOS Studio, create a new graph in your Studio organization. Choose "Supergraph" for your graph architecture. -1. Publish your monolith schema to GraphOS Studio as a subgraph with the following command (modify your `--routing-url` and `--schema` path as needed): - - ```sh - rover subgraph publish --name monolith \ - --schema ./schema.graphql \ - --routing-url http://monolith.prod.svc.cluster.local/graphql \ - --convert # necessary if you're publishing to an existing variant - ``` - -1. Deploy an instance of the GraphOS Router to your environment. - - - Self-hosting the GraphOS Router is limited to [GraphOS Enterprise plans](https://www.apollographql.com/pricing). Other plan types use [managed cloud routing with GraphOS](/graphos/cloud-routing). Check out the [pricing page](https://www.apollographql.com/pricing/) to learn more. - - -1. Set up [header propagation](/router/configuration/header-propagation/) so that the monolith receives any necessary headers from the router. -1. Set up internal routing rules to redirect client requests to the router instead of your monolith. -1. Enable usage metrics reporting to GraphOS Studio. -1. Add [subgraph checks](/graphos/platform/schema-management/checks/) to your monolith's CI pipeline. - -At this point, client requests go to your new router instead of the monolith, but it's serving the same schema so clients won't know the difference. - -Not only are you prepared to federate your schema, you now have field-level visibility into graph usage and breaking change detection. - -### 2. Identify entities - -Next, look through all the types in your schema and identify possible [entities](/graphos/schema-design/federated-schemas/entities/intro#entity-overview). Entities are types that form the foundation of your data model, and they must include fields that can uniquely identify each instance of them. - -Consider this schema for a travel booking site: - - - -```graphql -type Account { - id: ID! - username: String - user: User - profile: Profile -} - -type Address { - line1: String - line2: String - city: String - state: String - zip: String -} - -type Airline { - id: ID! - name: String -} - -type Airplane { - id: ID! - class: String -} - -type Airport { - code: AirportCode! - airlines: [Airline] -} - -type Amenity { - name: String - description: String - photoUrl: String -} - -type Bed { - id: ID! - size: BedSize - room: Room -} - -type CancellationPolicy { - text: String - updatedAt: DateTime -} - -type Flight { - number: FlightNumber! - airplane: Airplane - origin: Airport - destination: Airport - scheduledTakeoff: DateTime -} - -type Hotel { - id: ID! - name: String - address: Address -} - -type Profile { - name: String - address: Address - phone: String - email: String -} - -type Reservation { - account: Account - flights: [Flight] - hotels: [Hotel] -} - -type Room { - number: ID! - floor: Int - hotel: Hotel -} - -type Seat { - number: ID! - airplane: Airplane -} - -type User { - id: ID! - account: Account - username: String - reservations: [Reservation] -} - -type Query { - me: User - searchHotels(input: SearchHotelInput!): [Hotel] - searchFlights(input: SearchFlightInput!): [Flight] -} -``` - - - -Types such as `User`, `Reservation`, `Flight`, and `Hotel` are uniquely identifiable, whereas `Profile`, ` CancellationPolicy`, and `Amenity` are basically groups of attributes attached to those entities. - -### 3. Group entities - -After you've identified your entities, group them by their logical domain or concern. These groups usually correspond to product boundaries, but they might also be team boundaries. This is how you'll determine how many subgraphs you'll end up with. - -| Accounts domain | Flights domain | Hotels domain | -| --------------- | -------------- | ------------- | -| `Account` | `Airplane` | `Bed` | -| `User` | `Airline` | `Hotel` | -| | `Flight` | `Reservation` | -| | `Reservation` | `Room` | -| | `Seat` | | - -### 4. Rank entities by ease of migration - -When you're deciding how to start migrating types to other subgraphs, it's helpful to consider a few things first: - -#### How many related types will you have to migrate at the same time? - -Count the number of value types associated with an entity. You'll need to copy all those types over to the new subgraph when you migrate the entity. Entities with fewer related scalars, enums, and non-entity object types will be a bit easier to migrate. - -You won't need to move related entities at the same time as long as you can return an [entity reference](/graphos/schema-design/federated-schemas/entities/contribute-fields#referencing-an-entity-without-contributing-fields). For example, you can move the `Room` type if you have access to the `Hotel` foreign key: - -```graphql title="Hotels subgraph" -type Room @key(fields: "number") { - number: ID! - floor: Int - hotel: Hotel -} - -type Hotel @key(fields: "id", resolvable: false) { - id: ID! # comes from rooms.hotel_id in the database -} -``` - -It might be safer and easier to move the entire `Room` type but only a "stub" of the `Hotel` type. The query planner can fetch the rest of the `Hotel` fields from the monolith until you move that type as well. - -#### How complex will your query plans become during the migration? - -If you start by moving a type that's deeply interconnected with other types, you might introduce unnecessary complexity to your router's query plans. For example, consider this query: - -```graphql -query MyFlights { - me { - reservations { - flights { - ...FlightDetails - } - } - } -} -``` - -This query returns a list of `Reservation` objects belonging to a particular `User`, and each `Reservation` contains a list of `Flight`s. If you start by moving the `Reservation` type to another subgraph, this query results in an "A→B→A" query plan (fetching the `User`, then the `Reservation`, then the `Flight` in three serial subgraph fetches): - -```mermaid -flowchart TD - A(monolith) --> B(subgraph) - B --> C(monolith) -``` - -A better choice at this stage might be to move the `Flight` type so that the query plan is much more efficient, fetching both the `User` and `Reservation` together before fetching the `Flight`: - -```mermaid -flowchart TD - A(monolith) --> B(subgraph) -``` - -When you move a type to another subgraph, you should also move all root-level fields that return that type (such as `Query.flight(id:)`. This way, objects of that type can be returned with only a single subgraph operation in the best case. And in the general case, the query plan can fetch any additional data with fewer total subgraph operations: - -```mermaid -flowchart TD - A(subgraph) --> B(monolith) -``` - -Inevitably, some query plans become more complex while you're migrating types between subgraphs. By ranking your entities and moving the lowest-impact ones first, you can minimize this increase. - -## Implementation - -### 1. Make your monolith a real subgraph - -Now that you have a migration plan, you can start making schema and code changes. The first change is to add the [Apollo Federation subgraph specification](/federation/subgraph-spec/) to the monolith. The steps involved depend on which [Apollo-Federation-compatible library](/graphos/reference/federation/compatible-subgraphs) you use with your monolith's language and framework. - -The most important functionality to add is defining your entities (by adding `@key` directives) and adding their [reference resolvers](/graphos/schema-design/federated-schemas/entities/intro#defining-an-entity). - -### 2. Deploy your new subgraph - -Start with an empty subgraph to quickly set up your deployment and continuous integration pipelines. You can use this stub subgraph schema, which won't affect the client-facing schema: - -```graphql -extend schema @link(url: "https://specs.apollo.dev/federation/v2.0", import: ["@shareable", "@inaccessible"]) - -type Query { - _todo: String @shareable @inaccessible -} -``` - -After your new subgraph is deployed, set up [schema checks and publishes](/rover/commands/subgraphs#publishing-a-subgraph-schema-to-graphos) so that you can catch composition errors quickly and start contributing to the supergraph. - -### 3. Move an entity along with related types and relevant root fields - -1. Start by marking all the value types (enums and non-entity object types) you're going to move to the subgraph as `@shareable` in the monolith. -2. Copy the types and fields over to the subgraph schema and port their resolvers from the monolith. -3. Deploy the subgraph and test it by making calls to it directly. Use the [`_entities` root field](/federation/building-supergraphs/subgraphs-overview/#query_entities) to test joins between entities. - -When you're satisfied with the behavior and performance of your new subgraph, you can start moving all traffic to it and cleaning up the monolith. - -1. Use the [`@override`](/graphos/reference/federation/directives/#override) directive to mark fields in the subgraph with `@override(from: "monolith")`, telling the query planner to prefer the new subgraph over the monolith. -2. Remove types and fields from the monolith schema. -3. Delete unneeded resolvers from the monolith. -4. Remove `@override` directives from the subgraph. -5. Remove `@shareable` from types and fields in the subgraph when appropriate. - -### 4. Migrate additional functionality out of the monolith as desired - -Towards the end of the migration, you can decide whether to leave the monolith in place to handle the few entities that sit in the middle of your domain (such as `User`), or completely deconstruct the monolith into new services and decommission it. Either way, your newly federated GraphQL API is well-positioned to scale even larger in the future. diff --git a/docs/source/reference/migration/migrating-from-stitching.mdx b/docs/source/reference/migration/migrating-from-stitching.mdx deleted file mode 100644 index 03a8532ee..000000000 --- a/docs/source/reference/migration/migrating-from-stitching.mdx +++ /dev/null @@ -1,188 +0,0 @@ ---- -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/)