Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Start for Free

Apollo Federation Quickstart

Build a federated GraphQL API with Apollo Federation

combines microservices into a single API, providing real-time access to all your for all your client applications.


By the end of this quickstart, you'll have set up a federated GraphQL API—also known as a supergraph—that integrates data from products, users, and inventory services. Along the way, you'll learn about tools like the and .

To learn more about Apollo Federation and the benefits of using it with , check out these resources:

  • Introduction to Apollo Federation
  • Introduction to GraphOS


To complete this quickstart, you must have the following:

If you haven't already, set these up before continuing.


Setting up a with GraphOS takes a few steps:

  1. Install the Rover CLI.
  2. Start local development.
  3. Publish your services—known as subgraphs in the context of a supergraph—to GraphOS.

Once you've published your , you can use GraphOS Studio to explore and better understand your supergraph.

Step 1. Install the Rover CLI

Rover is Apollo's CLI for managing all kinds of , including subgraphs and . You'll use it throughout this quickstart.


Even if you already have installed, update your version by completing this step.

Install the latest Rover release with the appropriate command for your system:

MacOS / Unix-like
curl -sSL | sh
iwr '' | iex

After installing, run rover -V in your terminal to confirm it installed successfully. Verify that the printed version number matches the latest release. If it doesn't, you might need to manually delete an outdated installation.

Now that you've installed Rover, you're ready to start local development with your supergraph!

Step 2. Start local development

Running a supergraph entails running its router. The is the single access point to your supergraph for clients. The router receives incoming and intelligently routes them across component services before returning a unified response.


In this step, you'll do the following:

  1. Locally run the subgraphs.
  2. Locally run your router.
  3. your router to ensure it's working as expected.

Run subgraphs

To start local development, you must first get the subgraphs in the retail demo up and running. From the root directory, install dependencies:

npm install

Then run the subgraphs:

npm run dev:subgraphs

In your terminal, you should see notifications for each :

Setting up [products] subgraph at http://localhost:4001/products/graphql
Setting up [orders] subgraph at http://localhost:4001/orders/graphql
Setting up [users] subgraph at http://localhost:4001/users/graphql

Keep these subgraphs up and running so that the router can them.


The retail demo contains the code behind each of these subgraphs, including their schemas, , and mock data. These files are provided for your reference—understanding them isn't necessary to complete this quickstart. Check out these tutorials to learn more about GraphQL schemas and resolvers.

Run router

With your subgraphs running, you can use Rover to start the router locally. To do so, use the rover dev command with the --supergraph-config and --router-config options.

The retail demo comes with supergraph-config-dev.yaml and router-config-dev.yaml YAML configuration files that include subgraph names, URLs, and router configurations.

In a different terminal window from the one where the subgraphs are running, run this command:

rover dev \
--supergraph-config supergraph-config-dev.yaml \
--router-config router-config-dev.yaml

When you first start the rover dev process, you'll see the following happening in the terminal:

  • Rover obtains the provided and starts sessions for each of them.

    🛫 starting a session with the 'discovery' subgraph
    🛫 starting a session with the 'checkout' subgraph
    🛫 starting a session with the 'users' subgraph
    🛫 starting a session with the 'inventory' subgraph
    🛫 starting a session with the 'orders' subgraph
    🛫 starting a session with the 'shipping' subgraph
    🛫 starting a session with the 'products' subgraph
    🛫 starting a session with the 'reviews' subgraph
  • Rover uses Apollo Federation to compose a by adding subgraph schemas one at a time.

    🎶 composing supergraph with Federation v2.8.0
    ✅ successfully composed after adding the 'products' subgraph
    • The order in which Rover adds subgraphs is undefined, so you might see errors like the following during intermediate steps.
    error[E029]: Encountered 1 build error while trying to build a supergraph.
  • When composition completes successfully, Rover starts a locally running router session and provides it with the supergraph schema.

    🚀 your supergraph is running! head to http://localhost:4000 to query your supergraph


    This message may be followed by composition errors and successful composition notifications. As long as you can access http://localhost:4000, your router is running locally.

  • Rover starts watching the provided subgraph schemas for changes.

    👀 watching ./subgraphs/products/schema.graphql for changes
    • Rover recomposes the supergraph schema whenever it detects one. Recomposition automatically reloads the router.

Nice! You've now got a supergraph running locally.

Query your router

To ensure everything works as expected, you can query your router in the that Rover automatically starts up.

  1. Open localhost:4000 in a browser to access your locally running router. It should look something like this:

    The Apollo Sandbox with a prepopulated example query.
  2. Run the following query by copying and pasting it into the Operation window and then clicking the play button labeled ExampleQuery.

query ExampleQuery {
listAllProducts {
variants {
  1. Confirm that once you run the , you see the following in the Response panel on the right:

    This operation requests a list of all products from the products subgraph. You can remove like mediaUrl or add fields like releaseDate to the operation to see how the reponse changes.

    Next, you'll execute an operation that demonstrates the power of federation.

  2. Replace the example query in the Operation window with the following. Run it by clicking the play button, now labeled GetCart.

    # Get the current user's cart with all the items and their product info as well as the price.
    query GetCart {
    user {
    cart {
    items {
    inventory {
    product {
  3. In the Response panel, you should see an error like this: Could not locate user by id. Please specify a valid x-user-id header like user:1.

    This error appears because the operation retrieves a particular user's shopping cart given the user's ID. The operation expects the user ID to be in the request header. You can include it in the request headers in Sandbox by doing the following:

    • Open the Headers tab below the Operation editor.
    • Click + New header.
    • Enter x-user-id as the header key and user:1 as the value.
    The GraphOS Studio Explorer with a GetCart operation and headers.
  4. Rerun the request. In the Response panel, confirm you see the following:

Excellent! You've used one request to your router to get data from across different services. In the last part of this local development step, you'll learn more about how the router accomplished this.

Inspect query plans

The GetCart operation is powerful because it gathers data across various subgraphs: users, products, inventory, and more. Sandbox displays an operation's Query Plan to help you understand how the router intelligently orchestrates subrequests to these subgraphs.

A is a blueprint for dividing a single incoming operation into one or more operations that are each resolvable by a single subgraph. You can view the query plan instead of the response by clicking Response and selecting Query Plan.

Apollo Sandbox shows a query plan diagram for an operation.

are a powerful tool for understanding operations, whether they're run locally or from client applications.

In the last step of this tutorial, you'll publish your locally running subgraph schemas to GraphOS Studio to learn more about your supergraph.

Step 3. Publish your subgraphs

To create a supergraph, you individually publish each to GraphOS. Whenever you publish a subgraph schema, GraphOS attempts to compose all the latest subgraph schemas into a single supergraph schema. If this composition succeeds, GraphOS updates your router with the result.

In this step, you'll create an empty supergraph in GraphOS Studio and then publish subgraph schemas to it using Rover.

Create supergraph

  1. If you don't yet have a GraphOS Studio account, create one now.

  2. If you're starting from a new Studio account, click Connect a GraphQL API when prompted. If working from an existing Studio account, click + Create New Graph on the top right of the page.

  3. Enter a Graph title, for example Federation Quickstart. Leave the Graph Architecture as Supergraph (Default) and Visible to Team Members as On. Click Next.

  4. A Publish your schema using Federation dialog appears. Copy the entire example code block to a local text file using the copy button.

    A dialog from GraphOS Studio displays a hidden API key and graph ref.

    It should look something like this:

    APOLLO_KEY=service:Federation-Quickstart:••••••••••••••••••••• \
    rover subgraph publish Federation-Quickstart@current \
    --schema ./products-schema.graphql \
    --name your-subgraph-name \
    • The protected value that appears after APOLLO_KEY= and begins with service: is your .
    • The value that appears after rover subgraph publish is your . By default, it ends with @current.
    • You'll use both your graph API key and graph ref in the next step.

    ⚠️ CAUTION

    API keys are secret credentials. Never share them outside your organization or commit them to version control. Delete and replace API keys that you believe are compromised.

  5. Leave the dialog open; you'll complete setup with Rover.

Publish subgraph schemas

Complete the next steps back in your terminal:

  1. Ensure your subgraphs are still running locally.

  2. Take the multi-line command you copied from Studio and replace the last three lines with the following:

    --schema ./subgraphs/products/schema.graphql \
    --name products \
    --routing-url http://localhost:4001/products/graphql

    It should now look something like this:

    APOLLO_KEY=service:<GRAPH_API_KEY> \
    rover subgraph publish <GRAPH_REF> \
    --schema ./subgraphs/products/schema.graphql \
    --name products \
    --routing-url http://localhost:4001/products/graphql
    • The --schema option specifies the path to the schema file to publish.

    • The --name option specifies the name of the subgraph.

    • The --routing-url is the address the router should send subrequests for this particular subgraph to.


      In a production supergraph, a subgraph's routing-url is generally its public endpoint.

  3. While still in the retail demo's root directory, open a new terminal window. Paste and run your updated multi-line command.

    • Because the command provides a localhost address for the routing-url, the terminal will confirm that you want to publish. Enter Y.

    • If the command is successful, you'll see the following in your terminal:

      A new subgraph called 'products' was created in <GRAPH_REF>
      The supergraph schema for <GRAPH_REF> was updated,
      composed from the updated 'products' subgraph
    • After a few moments, the GraphOS Studio dialog you left open when creating an empty supergraph will show Schema published on the bottom left.

    A dialog from GraphOS Studio updates to show a schema has been published.
  4. Run the rover subgraph publish command for the inventory subgraph, substituting your graph ref. You no longer need to include the first line containing your graph API key:

    rover subgraph publish <GRAPH_REF> \
    --schema ./subgraphs/inventory/schema.graphql \
    --name inventory \
    --routing-url http://localhost:4001/inventory/graphql
  5. Do the same for the users subgraph, substituting your graph ref:

    rover subgraph publish <GRAPH_REF> \
    --schema ./subgraphs/users/schema.graphql \
    --name users \
    --routing-url http://localhost:4001/users/graphql

Congrats! With these subgraphs published, you can explore and interact with them and the supergraph composed of them in GraphOS Studio.


The retail demo contains other subgraphs—for example, the reviews and shipping subgraphs. The three you've just published are enough to understand what GraphOS Studio has to offer, but you can publish the others if you want to explore their schemas.

Explore your supergraph

Once you've published subgraphs, open the Schema page from the left nav in Studio to explore the composed supergraph schema as well as individual subgraph schemas and the relationships between them.

  • The Reference tab lets you view and filter your schema's type and definitions. For example, select Objects, then User, to see all of the user type's fields and which subgraphs provide them.

    The GraphOS Studio Schema Reference page shows filterable list of types and fields.
  • The SDL tab displays your supergraph's and supergraph schema, filterable by subgraph. Viewing the supergraph () allows developers to see exactly how subgraph schemas are composed together.

    The GraphOS Studio Schema SDL page has a left nav listing all subgraphs.
  • The Visualization tab provides a filterable, navigable, ical representation of your supergraph schema. Once you start collecting metrics on your supergraph, you can use the visualization tool to create heatmaps to identify fields that are most frequently used, or have the highest latency or errors.

    The GraphOS Studio Schema Visualization page shows an interactive representation of an e-commerce supergraph schema including Orders, Users, Variants, Products, etc.

GraphOS also offers tools for managing your schema, including , checks, and linting. Additionally, GraphOS tools help you integrate schema publication into your DevOps workflows.

Once you deploy your router, either by self-hosting it or using the Apollo-managed cloud option, you can use it to collect and export telemetry to GraphOS Studio and other observability and application performance monitoring (APM) tools.

Next steps

Depending on your goals, you have several options for learning more about GraphOS' capabilities or moving your supergraph closer to production:

  • Learn about the different router types to decide which type best fits your use case.

  • Learn more about Studio features, including proposals, linting, and checks.

    • If you'd like a visual tour of some of these features, check out the video below.

  • Learn about GraphOS metrics and router telemetry.

  • Check out the rover template command to quickly start a new GraphQL project or explore implementations in different libraries and languages.

Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy