4. Running the router


Our soundtracks API is now reporting to β€”but we still need to start up our to pull the pieces together.

In this lesson, we will:

  • Run the
  • Explore metrics
  • Describe how the creates to resolve across multiple s

The Apollo Router

We've taken care of two of our steps on the journey from to . We've centralized a place in Studio for all of the details about our graph to liveβ€”but we're still missing the piece that routes different parts of our to different services. Next up: let's get our running!

The is a high-performance router written in Rust. It's available as an executable binary that you can configure in just a few steps.

Installing the router

In the terminal, let's navigate up a level in our project, then into the router directory. So far, we have the .env file in here with our environment variables (APOLLO_GRAPH_REF and APOLLO_KEY), along with a file called config.yaml. This is a configuration file which lets us customize certain aspects about how the runs.

πŸ“¦ router
┣ πŸ“„ config.yaml
β”— πŸ“„ .env

We'll download the by running the install command in the terminal.

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

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

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

πŸ“¦ router
┣ πŸ“„ config.yaml
┣ πŸ“„ .env
β”— πŸ“„ router

Router configuration

Let's take a peek inside the config.yaml file. This file enables us to customize our 's behavior.

all: true
mode: spec_compliant

For now, we've set a few options, including the port that the should run on (under the supergraph.listen property). We also configured a setting to include all the errors that bubble up. By default, the redacts the details of subgraph errors in its responses, and we might see an error message like "Subgraph errors redacted". In production environments, this property is usually set to false, but it'll be helpful if you run into any issues following along in this tutorial.

Lastly, our config.yaml file has some telemetry configuration which reduces the kinds of errors we'll see in our terminal output.

Note: To learn more about other options available for configuring the , check out the documentation.

Running the router

Next up: we'll tell the which to connect to, and how to authenticate to it. This means that we'll pass it our APOLLO_KEY and APOLLO_GRAPH_REF values!

From the router directory, run the command below, replacing the placeholder <APOLLO_KEY> and <APOLLO_GRAPH_REF> with your values from .env. We'll also pass the --config flag so the will use the configuration details from config.yaml.


We'll see a few lines of output, and finally a message that our router is running on port 5000, ready to receive queries!

Let's copy this address.

This is the entrance to our : it's where anyone any part of our schema will send their requests to. Let's add this detail to !

Connecting the router to GraphOS

Flipping back over to Studio, click on the README tab in the sidebar. Next, tap the Connection Settings link at the top of the page.


The graph README page, highlighting that the graph does not yet have an endpoint

We'll paste the address we copied ( as the endpoint, then save.


The connection settings modal, highlighting the input where we can paste our endpoint

Testing our schema

Let's put together a that retrieves the titles and descriptions of our featured playlists. Select the Explorer tab from the sidebar and paste in the following .

query GetFeaturedPlaylists {
featuredPlaylists {

Now let's run this , and... fantastic! We've got data!

GraphOS Studio and the supergraph

Though our and soundtracks are running locally, we've got all the pieces in place for production: our can receive requests, and it consults the in to know where each piece of a should be sent. Right now, it only has one subgraph to worry about: all requests will land in our soundtracks to be fulfilled!

Even so, has already gathered insights about our API: we can see what has been queried for, how many times, and if any errors were encountered. Let's jump into our metrics in Studio.

Operation metrics

First, we'll check out the Insights page.


The Insights page in Studio

The Operations tab in the first panel on the left gives us an overview of request rates, service time, and error percentages, as well as specifics for each individual operation we wish to inspect.

By filtering this page to a particular , we'll see more specific details about its usage, as well as its signature, which is the shape of the . We can see the number of requests that have been made and how long each request takes over time.


The Insights page in Studio, filtered to show metrics for a specific operation: GetFeaturedPlaylists

Note: We recommend that clients clearly name each they send to the , so we can easily view them in our metrics.

Field metrics

Next, let's check out metrics. Head over to the Fields tab.

For each , we can explore more specific datapoints, including the number of requests that have included it.


The Insights page in Studio, on the Fields tab

We can use both and metrics to monitor the health and usage of our 's types and fields and determine where we can start to improve, based on how they're performing and how our clients are using them. Because we can see which fields our clients are using AND how frequently, these metrics also let us know when it's safe to remove unused fields from our graph.

We've reviewed our metrics, and we're ready for our to grow: next, let's take a look at how we keep adding pieces to our API.

Key takeaways

  • metrics provide an overview of operation request rates, service time, and error percentages within a given time period or for a specific operation.
  • metrics include the requesting metric, which lists the number of operations in a given period that have included the particular field.
  • The uses the to create a for the incoming . The query plan is a list of smaller operations the router can execute on different to fully resolve the incoming operation.
  • The carries out the by executing the list of on the appropriate .
  • The combines all the responses from the into a single JSON object, which it sends back to the client.

Up next

Let's see this process in action! In the next lesson, we'll introduce a whole new domain in the form of a new : it's an activity we're all familiar with, and it's much more fun when we've got music to set the mood. It's a subgraph all about recipes!


Share your questions and comments about this lesson

This course is currently in

. Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.