8. Router configuration and Uplink
4m

Overview

So far, FlyBy's subgraphs are running and their schemas have been published, but we still need one piece to tie everything together: the router.

In this lesson, we will:

  • Set up the Apollo Router locally
  • Connect our router to Apollo Studio
  • Send our first query to our supergraph

✏️ Downloading the router

The Apollo Router is a high-performance graph router built in Rust. It's available as an executable binary that you can add to your project in a few steps:

  1. Open a terminal window and navigate to the router directory in the FlyBy project.

    cd router

    So far, we only have the .env file in here with our environment variables.

    📦 router
    ┣ 📄 .env
  2. We'll download the Router by running the install command in the terminal.

    router
    curl -sSL https://router.apollo.dev/download/nix/latest | sh

    Note: Visit the official documentation to explore alternate methods of downloading the Router.

  3. Now when we check the contents of our router directory, we'll see that we have a new file also called router!

    📦 router
    ┣ 📄 .env
    ┗ 📄 router

✏️ Running the router

  1. Back in the same terminal window, run the command below. You'll need to replace the <APOLLO_KEY> and <APOLLO_GRAPH_REF> placeholder values with your supergraph's corresponding values from the router/.env file. This command starts up the router locally and tells the router which supergraph to connect to.

    APOLLO_KEY=<APOLLO_KEY> APOLLO_GRAPH_REF=<APOLLO_GRAPH_REF> ./router
  2. We'll see a few lines of router output, and finally a message that our router is running on port 4000, ready to receive queries!

    Let's copy this address, we'll need it to set our connection settings in Studio. This tells outside consumers of our API what endpoint they can use to query our schema.

    GraphQL endpoint exposed at http://127.0.0.1:4000/ 🚀

    Note: Because our router is currently running at http://127.0.0.1:4000, it's not actually accessible to the outside world. But we can still add it to our configuration settings, which will let us query the router from our own machines.

✏️ Connecting the router to Apollo Studio

Let's flip back over to Studio.

  1. Click on the README tab in the sidebar.

  2. Next, tap the Connection Settings link at the top of the page.

    studio.apollographql.com/graph/flyby/home?variant=current
    The Connection Settings link to add an endpoint
  3. We'll paste the router address we copied (http://127.0.0.1:4000) as the endpoint, then save.

    studio.apollographql.com/graph/flyby/home?variant=current
    The Connection Settings modal to add an endpoint

Let's get to querying our supergraph!

✏️ Testing our schema

  1. Select the Explorer tab from the sidebar.

  2. Let's put together a query that retrieves data from both of our subgraphs. We'll call our query GetLocationsAndLatestReviews.

  3. Now let's fire in some fields. We'll start with locations. Click the plus button () next to Fields to add all the location fields to our query.

    Next let's go back and add latestReviews, and all the reviews subfields.

    Our query should look like this:

    query GetLocationsAndLatestReviews {
    locations {
    id
    name
    description
    photo
    }
    latestReviews {
    id
    comment
    rating
    }
    }
  4. Before we run the query, let's change the Response dropdown on the right to Query Plan Preview. This shows us a diagram for the query plan the router will use to resolve our current operation.

    studio.apollographql.com/graph/flyby/explorer?variant=current
    Viewing the Query Plan Preview panel for a query, with steps broken down in a diagram
  5. By choosing the icon to Show plan as text, we'll see a more detailed breakdown of the query plan. We won't worry about all the syntax here, but we can get a general idea of how the router plans to handle this query: the locations subgraph will resolve the locations fields, and the reviews subgraph will handle latestReviews and its subfields.

    studio.apollographql.com/graph/flyby/explorer?variant=current
    Viewing the Query Plan Preview panel for a query, with steps broken down in text
  1. Now let's run this query.

    studio.apollographql.com/graph/flyby/explorer?variant=current
    Querying both subgraphs at once for data

Fantastic! We can see that the data object in our response contains both locations and reviews.

This is huge. We've just unlocked one of the powers of our supergraph: we can write one query to our router and hit both subgraphs at once!

Practice

What information does the Query Plan Preview in Apollo Studio include?

Key takeaways

  • The Apollo Router is an executable binary file that can be downloaded and run locally.
  • The Query Plan Preview inspects the GraphQL operation in the Explorer and outputs the query plan the router will execute to resolve the operation.

Up next

Congratulations, we now have a working supergraph! Our frontend team can get back all the data they need from a single GraphQL operation, and we've improved our development experience by modularizing the backend!

But there's still one problem we need to solve.

Remember those three fields we still haven't added to our schema? You remember! Here's that schema agreement again, to jog your memory:

The FlyBy schema diagram, updated to check off the fields we've added to the reviews and locations subgraphs so far

Even though our router can query each subgraph separately, we can't associate data between the two subgraphs yet.

Well, next up we'll learn about the feature that will make coordination between our subgraphs possible: entities.

Previous
Next