Docs
Launch GraphOS Studio

Moving to Apollo Federation 2

Upgrade your supergraph incrementally at any pace


📣 If you haven't yet, see what's new in Federation 2.

You can (and should!) move your 1 to Federation 2 incrementally, one component at a time. Your will work as expected after each step in the process, even while some of your continue using Federation 1 schemas.

Each individual step of moving your has its own benefits, so it's useful to complete as many steps as you're ready to complete. You can always finish the rest later.

Here are the three steps for moving to Federation 2:

Upgrade your
gateway
Use Federation 2
composition
Update individual
subgraphs

  1. Upgrade your gateway to support Federation 2.

    You can upgrade to either of the following:

    • The Apollo Router, a high-performance precompiled executable (recommended)
    • Version 2.x of the @apollo/gateway library, along with version 4.x of
  2. Begin composing your with Federation 2 logic.

  3. Update your individual to use Federation 2 features and .

As with all infrastructure changes, we strongly recommend completing each of these steps with a test instance of your before performing them in production.

If you encounter an issue while moving your to Federation 2, please describe the issue in the community forums.

Step 1: Upgrade your gateway

For your Federation 1 to support Federation 2, you first need to upgrade its gateway to one of the following:

  • The Apollo Router. This is a high-performance, precompiled executable that provides many benefits over the Node.js-based gateway.
    • We recommend moving to the unless you've extended your Node.js gateway with functionality that the doesn't currently support (this is uncommon).
  • Version 2.x of the @apollo/gateway library, with version 4.x of

Both the and @apollo/gateway v2.x support Federation 1! You can upgrade to either without making any other changes to your Federation 1 , and it will work as expected.

Moving to the Apollo Router

  • To get started running the , see the quickstart.
  • For guidance on moving to the from your Node.js-based gateway, see this article.

Upgrading @apollo/gateway and Apollo Server

The @apollo/gateway library supports Federation 2 in version 2.0.0 and later. These versions of @apollo/gateway require version 16.0.0 or later of the graphql library.

You can install updated versions of these libraries in your gateway project with the following command:

npm install @apollo/gateway graphql

3.x supports these updated library versions, however Apollo Server 3.x is deprecated! Therefore, we strongly recommend also upgrading your gateway to 4.

Step 2: Configure your composition method

Federation 2 uses a completely new method to compose . This method is backward compatible with Federation 1 , and it provides the following benefits even for Federation 1 subgraphs:

  • Helpful composition hints when schema definitions are inconsistent between your s
  • Support for interfaces implementing other interfaces (which Federation 1 doesn't support)

Follow the instructions below to configure whichever method(s) you currently use:

After you configure these changes, make sure your is using your newly created Federation 2 . (If you're using , your router will fetch the new schema from Apollo automatically.)

Your Federation 1 are now composed using Federation 2 ! The natural next question is, "What does this change about the behavior of those subgraphs?" And until the next step, the answer is: nothing!

If your is not successfully composing with Federation 2, see Breaking changes for the most common causes.

Step 3: Update individual subgraphs

You can update your subgraphs one at a time! The steps below describe how to modify a single for Federation 2, and you can perform these steps for a given subgraph whenever's convenient for your team.

Federation 2 provides powerful new features that require making some changes to your . These features include:

  • Selectively sharing types and across with @shareable
  • Safely migrating from one to another with @override
  • Hiding internal routing from consumers with @inaccessible

The schema changes you make are backward incompatible with Federation 1, which means you won't be able to use Federation 1 anymore unless you revert those changes.

Update your subgraph library

To use new Federation 2 features and their associated , it's helpful to update your library to a version that automatically supports those directives.

  • If your uses and the @apollo/subgraph library, update @apollo/subgraph to version 2.0.0 or later like so:

    npm install @apollo/subgraph
  • If your uses another server library, check the compatibility table to see whether it supports Federation 2 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 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

Add the following definition to your :

extend schema
@link(url: "https://specs.apollo.dev/federation/v2.0",
import: ["@key", "@shareable"])

This definition identifies a schema as a Federation 2 schema, and it imports any federation-specific that the schema uses. Without this @link definition, considers a schema to be a Federation 1 schema, and it applies certain default settings for backward compatibility.

⚠️ Important: Depending on your schema, you might need to add other federated to the import array, such as @external or @provides.

See all Federation-specific directives.

Add directive definitions if needed

Currently, not all subgraph libraries provide built-in support for Federation 2 (such as @shareable). If your library doesn't provide this support, you need to add the following definitions to your :

Some libraries are "code-first" (they dynamically generate their schema from code) instead of "schema-first" (they use a static schema file). For code-first libraries, manually adding these definitions is less straightforward. If you encounter this with your library, please let us know by submitting an issue.

Definitions for all Federation 2 are available in this article. We work with library maintainers to help automatically add these schema definitions in as many libraries as possible.

Mark all value types as @shareable

By default in Federation 2, most schema are resolvable by only a single subgraph. In Federation 1, this is not true for value types:

Fed. 1 (invalid in Fed. 2)

Subgraph A
type Position {
x: Int!
y: Int!
}
Subgraph B
type Position {
x: Int!
y: Int!
}

For both to resolve the above in Federation 2, the @shareable is required in both schemas:

Fed. 2

Subgraph A
type Position {
x: Int! @shareable
y: Int! @shareable
}
Subgraph B
type Position {
x: Int! @shareable
y: Int! @shareable
}

You can also apply @shareable directly to a type definition (such as Position above). This is equivalent to applying @shareable to all of that type's .

For more details, see Value types.

Update entity definitions

Federation 2 introduces subtle but powerful changes to entities. These changes require corresponding updates to their definitions in your .

Remove unnecessary syntax

In Federation 1, an originates in one , and then other subgraphs extend the to add :

Fed. 1

Products (originating)
type Product @key(fields: "id") {
id: ID!
name: String!
price: Int
}
Inventory (extending)
extend type Product @key(fields: "id") {
id: ID! @external
inStock: Boolean!
}

In Federation 2, entities no longer have an originating . Instead, each subgraph can define an and contribute to it:

Fed. 2

Products
type Product @key(fields: "id") {
id: ID!
name: String!
price: Int
}
Inventory
type Product @key(fields: "id") {
id: ID!
inStock: Boolean!
}

Note the following in the Federation 2 above:

  • The Inventory no longer extends the Product .
  • The Inventory no longer marks the Product.id as @external.
    • The @external is no longer required for @key , but it is still required for @requires and @provides.
  • Both can resolve Product.id, even though it isn't marked as @shareable!
    • Unlike most , @key such as Product.id are @shareable by default. This is necessary for @key , because the gateway uses them to associate data from different with the same object.

Mark @provides fields as @shareable

The @provides enables a to resolve a particular only for specific paths. It's supported in Federation 2 as it is in Federation 1.

However, if a @provides a particular , that field must be marked as @shareable in each where it's always resolvable:

Fed. 2

Products
type Product @key(fields: "id") {
id: ID!
name: String! @shareable
price: Int
}
Inventory
type Product @key(fields: "id") {
id: ID!
name: String! @external
inStock: Boolean!
}
type Query {
outOfStockProducts: [Product!]! @provides(fields: "name")
}

Here, Query.outOfStockProducts in the Inventory @provides the Product.name . Therefore, that field must be marked as @shareable in the Products (and @external in the Inventory , as in Federation 1). Otherwise, a error occurs.

Modify @keys for entity stubs

In certain cases, a references an without contributing any to it. In Federation 1, these cases look like the following:

Fed. 1

Products
type Product @key(fields: "id") {
id: ID!
name: String!
price: Int
}
Reviews
type Product @key(fields: "id") {
id: ID!
}
type Review {
product: Product!
score: Int!
}

The Reviews above uses Product as the return type of the Review.product , so it needs to define a "stub" of the Product . This stub includes just enough information to identify a unique instance.

In Federation 2, stubs like Product should include resolvable: false in their @key , like so:

Fed. 2

Products
type Product @key(fields: "id") {
id: ID!
name: String!
price: Int
}
Reviews
type Product @key(fields: "id", resolvable: false) {
id: ID!
}
type Review {
product: Product!
score: Int!
}

Setting resolvable: false tells the gateway that a doesn't define a reference for a particular . This is most common when referencing an entity without contributing fields to it.


You're done! You should now have a Federation 2 that composes successfully and takes full advantage of new federation features. If you encounter an issue, please let us know in the community forums.

Previous
Changes from Federation 1
Next
Backward compatibility
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company