Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Launch GraphOS Studio

Moving a GraphQL monolith to Apollo Federation

Steps for migrating from a GraphQL monolith to multiple subgraphs with Apollo Federation


For a complete, step-by-step tutorial, check out Voyage II: Federating the monolith.

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 .

Here are the steps we recommend to convert a monolithic GraphQL API into a federated GraphQL API.

Planning & preparation

1. Put the Apollo Router in front of your existing API

Start the process by making a "federated graph of one". Your existing monolith can act as a without any changes.

  1. If you're not already publishing your to Apollo Studio, create a new graph in your Studio organization. Choose "" for your graph architecture.

  2. Publish your monolith to Apollo Studio as a with the following command (modify your --routing-url and --schema path as needed):

    rover subgraph publish --name monolith \
    --schema ./schema.graphql \
    --routing-url \
    --convert # necessary if you're publishing to an existing variant
  3. Deploy an instance of the Apollo Router to your environment.

    Self-hosting the Apollo is limited to Apollo Enterprise plans. Other plan types use managed cloud routing with GraphOS.

    Learn about Apollo plans.

  4. Set up header propagation so that the monolith receives any necessary headers from the .

  5. Set up internal routing rules to redirect client requests to the Apollo instead of your monolith.

  6. Enable usage metrics reporting to Apollo Studio.

  7. Add subgraph checks to your monolith's CI pipeline.

At this point, client requests go to your new Apollo instead of the monolith, but it's serving the same so clients won't know the difference.

Not only are you prepared to federate your , you now have -level visibility into graph usage and breaking change detection.

2. Identify entities

Next, look through all the types in your and identify possible entities. Entities are types that form the foundation of your data model, and they must include s that can uniquely identify each instance of them.

Consider this for a travel booking site:

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 s you'll end up with.

Accounts domainFlights domainHotels domain

4. Rank entities by ease of migration

When you're deciding how to start migrating types to other s, 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 of those types over to the new when you migrate the entity. Entities with fewer related s, enums, and non-entity s 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. For example, you can move the Room type if you have access to the Hotel foreign key:

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 s 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 's query plans. For example, consider this query:

query MyFlights {
me {
reservations {
flights {

This query returns a list of Reservation objects belonging to a particular User, and each Reservation contains a list of Flights. If you start by moving the Reservation type to another , this query results in an "A→B→A" query plan (fetching the User, then the Reservation, then the Flight in three serial fetches):


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:


When you move a type to another , you should also move all root-level s that return that type (such as Query.flight(id:). This way, objects of that type can be returned with only a single in the best case. And in the general case, the query plan can fetch any additional data with fewer total subgraph operations:


Inevitably, some query plans become more complex while you're migrating types between s. By ranking your entities and moving the lowest-impact ones first, you can minimize this increase.


1. Make your monolith a real subgraph

Now that you have a migration plan, you can start making and code changes. The first change is to add the Apollo Federation subgraph specification to the monolith. The steps involved depend on which Apollo-Federation-compatible library you use with your monolith's language and framework.

The most important functionality to add is defining your entities (by adding @key s) and adding their reference resolvers.

2. Deploy your new subgraph

Start with an empty to quickly set up your deployment and continuous integration pipelines. You can use this stub subgraph , which won't affect the client-facing schema:

extend schema
url: ""
import: ["@shareable", "@inaccessible"]
type Query {
_todo: String @shareable @inaccessible

After your new is deployed, set up schema checks and publishes so that you can catch composition errors quickly and start contributing to the .

  1. Start by marking all the value types (enums and non-entity s) you're going to move to the as @shareable in the monolith.
  2. Copy the types and s over to the and port their s from the monolith.
  3. Deploy the and test it by making calls to it directly. Use the _entities root field to test joins between entities.

When you're satisfied with the behavior and performance of your new , you can start moving all traffic to it and cleaning up the monolith.

  1. Use the @override to mark s in the with @override(from: "monolith"), telling the query planner to prefer the new over the monolith.
  2. Remove types and s from the monolith .
  3. Delete unneeded s from the monolith.
  4. Remove @override s from the .
  5. Remove @shareable from types and s in the 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.

Edit on GitHubEditForumsDiscord