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.
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.
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.
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:
✅
1
typeUser@key(fields:"id organization { id }"){
2
id:ID!
3
organization:Organization!
4
}
5
6
typeOrganization{
7
id:ID!
8
name:String!
9
}
In this example, the User's key fields are User.id and User.organization.id.
Federation 1 composition incorrectly allows a @key such as the following:
❌
1
typeUser@key(fields:"id organization"){
2
id:ID!
3
organization:Organization!
4
}
5
6
typeOrganization{
7
id:ID!
8
name:String!
9
}
This @key should break composition because it doesn't include at least one subfield of Organization.
A subgraph can annotate an entityfield with the @provides directive to indicate that the subgraph can resolve entityfields normally marked as @external on its own.
✅
Subgraph A
1
typeProduct@key(fields:"id"){
2
id:ID!
3
info:ProductInfo@external
4
}
5
6
typeProductInfo{
7
name:String!@external
8
inStock:Boolean!@external
9
}
10
11
typeQuery{
12
outOfStockProducts:[Product!]!@provides(fields:"info { name }")
13
discontinuedProducts:[Product!]!
14
}
In the above example, Subgraph A can resolve the Product.info.namefield when accessed through the outOfStockProductsquery. Any other path to Product.info.name results in an additional subgraph call.
Federation 1 incorrectly allows @provides usage like the following:
The above @providesdirectives 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.
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.
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/gateway0.x will continue to work as expected in @apollo/gateway2.x.