Overview

Let's bring our supergraph into the world.

In this lesson, we will:

• Convert our listings server into a federated subgraph
• Use our listings subgraph to create a new supergraph
• Set up our environment variables

From server to subgraph

Our listings server is already in good shape to become a subgraph, one part of a larger federated graph. There are just a few little tweaks we need to make.

Installing @apollo/subgraph

First, in the root of our listings directory, let's install the @apollo/subgraph package. This package provides a number of utilities that prepare a GraphQL service (like our listings server) to be integrated with other GraphQL services behind a single endpoint.

Using buildSubgraphSchema

Next, we'll jump into our listings/src/index.ts file. Here, we can import the buildSubgraphSchema function from @apollo/subgraph.

Below, we'll tweak our instantiation of ApolloServer just slightly. Instead of passing an object with our typeDefs and resolvers directly to the constructor function, we'll define an object with a property called schema.

As the value of the schema property, we'll call buildSubgraphSchema, passing it an array that contains our object of typeDefs and resolvers. Here's what that looks like.

Enabling Federation 2

For our subgraph to take advantage of all of the features available in Federation version 2, we need to add a specific definition called extend schema. This links to the version of federation that we want to use.

Copy the following line of code:

Next, we'll open up schema.graphql, and add the schema definition to the top of the file.

And that's it, our server is equipped with federation support!

From subgraph to supergraph

As we learned in the last lesson, we can make our single subgraph—listings qualifies as one now!—the very first piece in a supergraph. Growing from "sub" to "super" is actually a lot easier than it sounds.

Ready to go? Let's jump in.

Creating a new graph

1. Open a new browser window and go to GraphOS Studio.

2. If you haven't created a graph in Apollo Studio before now, you'll be prompted to do so. Otherwise, we can create a new graph by clicking the + Create New Graph button in the upper right corner of the dashboard.

   studio.apollographql.com

   

3. We'll give our graph a descriptive title, keep the default settings for Graph Architecture as "Supergraph", then click Next.

   studio.apollographql.com

   

   If you don't see the modal above, you may be on the wrong plan.

   Check your plan: Part of this course covers the self-hosted GraphOS Router, which requires an Enterprise or GraphOS Trial plan. You can still follow along if your organization is on a different plan, but you won't be able to complete certain hands-on tasks. You can also test out this functionality by signing up for a free trial.

4. We should now see a modal with options for publishing a schema.

   studio.apollographql.com

   

We're ready to publish our schema!

Publishing the listings schema

To publish our listings schema to our new graph, we'll use the Rover CLI. Rover lets us connect to our graph from the command line and publish schemas, but it needs a couple of pieces of data first.

• APOLLO_KEY: Your graph's API key, used to interact with a single graph in GraphOS. It starts with something like "service:your-graph-name". Note that this is different from your personal API key, which we used to authenticate Rover in the first lesson, and which grants you partial access to every graph in the organization you belong to.
• APOLLO_GRAPH_REF: The graph reference (or graph ref) for our supergraph, which we'll use to tell Rover where to publish our subgraphs. A graph ref starts with the graph's ID, followed by an @ symbol, followed by the graph variant.

We'll use these values again when we run the router, so we can store them in a new file we'll add to the router directory called .env.

Let's create that file now.

Storing variables

1. Go back to the configuration options in Studio that appeared after you created your supergraph. Make sure you're on the Schema Document tab.

2. First, make sure that the Supergraph Pipeline Track dropdown is set to Federation 2.7 Supergraph. This specifies that our supergraph should be built using the latest features of Apollo Federation.

   studio.apollographql.com

   

3. Below, take a little peek at the command for publishing a subgraph schema. We'll be running this command shortly, but for now, we're more interested in the APOLLO_KEY environment variable here.

   APOLLO_KEY=your-graphs-apollo-key \ 
     rover subgraph publish your-graph-name@current \
     --name products --schema ./products-schema.graphql \
     --routing-url http://products.prod.svc.cluster.local:4001/graphql

4. Click on the eye icon on the code block to reveal the full value of APOLLO_KEY. Copy APOLLO_KEY and its value into the router/.env file. We'll need it for the next step, and won't have access to the same key again through Studio.

   router/.env

   APOLLO_KEY=your-unique-apollo-api-key

5. Now let's go back to Studio to get our graph ref. The value we're looking for appears in the same code block, directly after the "rover subgraph publish" part of the command. We'll save this value as an environment variable as well, but we can access it anytime from our graph's home page.

   APOLLO_KEY=your-graphs-apollo-key \
     rover subgraph publish your-graph-name@current \ 
     --name products --schema ./products-schema.graphql \
     --routing-url http://products.prod.svc.cluster.local:4001/graphql

   Learn more: current and other graph variants

   Our graph ref references our supergraph's current variant, which is created by default. A variant represents a different environment where the supergraph runs. For example, we could have a variant for staging or pre-production, a common environment where we can test our schema changes before they go live. We could have another variant for production, which our real-life clients could use.

   To explore graph variants, how to create them, and how to make them public to the outside world, check out the GraphOS: Basics lesson, Sharing your supergraph.

Great! Before proceeding, we should make sure that we've saved both of our environment variables. We're about to put them to work!

We've got the values we need to publish our subgraphs!

The rover subgraph publish command

Rover has a command ready to help us with this important task: rover subgraph publish. This command pushes the latest version of a single subgraph schema to Apollo Studio.

To use this command, we need the graph ref for the supergraph we want to publish to and the following command line options:

Let's fill out this command for our listings subgraph.

1. Bounce back to the terminal and make sure we're in the listings directory of our project.

2. Now let's type out the rover subgraph publish command:

   Next, we'll paste in the value of our APOLLO_GRAPH_REF environment variable.

   For the name option, we'll pass in listings.

   For the schema option, we'll pass in the path to our schema, which from the root of the listings directory is ./src/schema.graphql.

   And for the routing-url option, we'll pass in localhost:4000.

   rover subgraph publish <APOLLO_GRAPH_REF> \
     --name listings \
     --schema ./src/schema.graphql \
     --routing-url http://localhost:4000

   Copy

   Note: We've used the \ character in this command to improve legibility by putting each command-line option on its own line. If you choose to type the entire rover subgraph publish command on a single line, you don't need to include the \.

3. You'll see the following message: The host localhost is not routable via the public internet. Continuing the publish will make this subgraph reachable in local environments only. Would you still like to publish? [y/N] Go ahead and tap the y key. We'll stick to local environments for this course!

4. If all is well in the world, running this command should output a message confirming that the subgraph has been published and the supergraph has been updated!

Reviewing results in Studio

Let's go back to Studio. We can click "See schema changes" in the modal to see what's changed in our supergraph.

This takes us to a new page called Launches. A launch is the process that runs every time we make a change to our supergraph. We'll take a closer look at launches in an upcoming lesson.

For now let's click on the Schema tab in the sidebar. The Schema Reference page lets us see all the types and fields in our composed supergraph schema. That's right—even though we've only published one subgraph so far, we already have a supergraph schema!

We see that our supergraph's Query type includes the two fields from the listings subgraph: featuredListings and listing. Each field is annotated with its description, any variables it requires, and which subgraph it belongs to.

Let's take a closer look at that supergraph schema. Click on the SDL tab at the top of the Schema page. Here we can see details about our published subgraphs, along with two additional schemas.

The API schema is the GraphQL API that gets exposed to your clients. It cleanly and logically represents the combination of your subgraph schemas. (We won't worry about this schema for now.)

The Supergraph schema is used by the router like a map, to define how incoming GraphQL operations can be divided up among the underlying subgraphs. We only have one at the moment, so all fields in an operation will be routed over to the listings subgraph.

Practice

Key takeaways

• We can use the rover subgraph publish command from the Rover CLI to publish our subgraph schemas to GraphOS.
• The supergraph schema consolidates all the types and fields across our published subgraphs. It also includes extra directives to help the router determine which subgraphs can resolve each field.

Up next

Our supergraph is set up, and we're just missing one piece: the router! Next up, let's get the router running, send it some queries, and inspect the insights from GraphOS!