Backward Compatibility in Apollo Federation 2
Navigating the transition from Apollo Federation 1 to Federation 2
Is official support ending for @apollo/gateway
v0.x?
Yes. As of 15 November 2022, @apollo/gateway
v0.x is officially deprecated, with end-of-life scheduled for 22 September 2023. @apollo/gateway
v2.x remains fully supported.
Learn more about deprecation and end-of-life.
Do I need to modify my subgraph schemas to use Federation 2?
Eventually. The process of moving to Federation 2 has three steps:
Upgrade your gateway to support Federation 2 (we recommend moving to the GraphOS Router ).
Begin composing your supergraph schema with Federation 2 composition logic.
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. ).
Step 3 does require some changes to your subgraph schemas, described here .
Breaking changes
As mentioned above, the following Federation 1 examples should produce composition errors, but they aren't detected. If your subgraph schemas include syntax that matches any of these, you need to update those schemas before moving to Federation 2.
See breaking changes
Invalid @key
directives
An entity's @key
consists of one or more of the entity's own fields
. If any of these fields have subfields, the @key
must also include at least one of those subfields:✅
1type User @key(fields: "id organization { id }") {
2 id: ID!
3 organization: Organization!
4}
5
6type Organization {
7 id: ID!
8 name: String!
9}
User
's key fields are User.id
and User.organization.id
.Federation 1 composition incorrectly allows a @key
such as the following:❌
1type User @key(fields: "id organization") {
2 id: ID!
3 organization: Organization!
4}
5
6type Organization {
7 id: ID!
8 name: String!
9}
@key
should break composition because it doesn't include at least one subfield of Organization
.Invalid @requires
directives
A subgraph can mark an entity field with the @requires
directive to indicate that it depends on fields and subfields from another subgraph:✅
1type Product @key(fields:"sku") {
2 sku: ID!
3 dimensions: ProductDimensions!
4}
5
6type ProductDimensions {
7 size: Int!
8 weight: Int!
9}
1extend type Product @key(fields:"sku") {
2 sku: ID! @external
3 dimensions: ProductDimensions! @external
4 shippingEstimate: Int! @requires(fields: "dimensions { size weight }")
5}
6
7type ProductDimensions {
8 size: Int!
9 weight: Int!
10}
shippingEstimate
field depends on the dimensions.size
and dimensions.weight
fields of Subgraph A.Federation 1 incorrectly allows a @requires
directive such as the following:❌
1type Product @key(fields:"sku") {
2 sku: ID!
3 dimensions: ProductDimensions!
4}
5
6type ProductDimensions {
7 size: Int!
8 weight: Int!
9}
1extend type Product @key(fields:"sku") {
2 sku: ID! @external
3 dimensions: ProductDimensions! @external
4 shippingEstimate: Int! @requires(fields: "dimensions { length depth }")
5}
6
7type ProductDimensions {
8 size: Int!
9 weight: Int!
10}
@requires
directive should break composition because it depends on subfields of ProductDimensions
that don't exist (length
and depth
).Invalid @provides
directives
A subgraph can annotate an entity field with the @provides
directive to indicate that the subgraph can resolve entity fields normally marked as @external
on its own.✅
1type Product @key(fields: "id") {
2 id: ID!
3 info: ProductInfo @external
4}
5
6type ProductInfo {
7 name: String! @external
8 inStock: Boolean! @external
9}
10
11type Query {
12 outOfStockProducts: [Product!]! @provides(fields: "info { name }")
13 discontinuedProducts: [Product!]!
14}
Product.info.name
field when accessed through the outOfStockProducts
query. Any other path to Product.info.name
results in an additional subgraph call.Federation 1 incorrectly allows @provides
usage like the following:❌
1type Product @key(fields: "id") {
2 id: ID!
3 info: ProductInfo @external
4}
5
6type ProductInfo {
7 name: String! @external
8 inStock: Boolean! @external
9}
10
11type Query {
12 outOfStockProducts: [Product!]! @provides(fields: "info")
13 discontinuedProducts: [Product!]!
14}
@provides
directives usage should break composition because it does not specify which subfields of ProductInfo
it can resolve. This is correctly caught and surfaced as an error in Federation v2 but Federation v1 incorrectly allows this usage.Can Federation 1 compose my Federation 2 subgraph schemas?
No, not after you convert at least one subgraph schema to a true Federation 2 schema.
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 .
Your plugins and customizations for @apollo/gateway
0.x
will continue to work as expected in @apollo/gateway
2.x
.
Compatibility table
Router/Gateway version | Federation 1 Composition | Federation 2 Composition |
---|---|---|
Apollo Router Core v1.x | 🟢 | 🟢 |
@apollo/gateway v2.x | 🟢 | 🟢 |
@apollo/gateway v0.x (deprecated) | 🟢 | ❌ |