4. Building out the subgraphs
6m

Overview

So now we have a plan for our ! To keep our focus on the Federation-specific concepts, the FlyBy starter repo already comes with base server code. Let's see what's been built so far.

In this lesson, we will:

  • Explore what's already been built for the locations and reviews servers
  • Use the @apollo/subgraph package to convert the locations and reviews servers from normal into .

Exploring the starter code

Let's start by checking out what's been built for our so far.

The locations subgraph

We'll start with the locations . Here's an architecture diagram showing the files in the subgraph-locations directory and how they're connected:

A diagram showing the architecture of the subgraph-locations directory, including the schema file, resolvers and a data source
  • index.js: Creates an ApolloServer instance that runs on port 4001. So far, this is just a normal , not a .
  • locations.graphql: A schema that defines the types and owned by the locations .
  • resolvers.js: Defines functions for the in the locations schema.
  • datasources/LocationsApi.js: Retrieves location data from the locations_data.json file.
    • Note: In a real-world application, this data source would talk to a REST API or a database, but we're in tutorial-land so we'll stick with the hard-coded fake data.
  • datasources/locations_data.json: A JSON object with hard-coded location data.

Take a moment to look over these files and familiarize yourself with their contents.

Let's update our schema agreement checklist with the that have been added to our locations so far:

The FlyBy schema agreement diagram from the previous lesson, with the fields for the locations subgraph checked off

The reviews subgraph

Next up, the reviews . The files in the subgraph-reviews directory have a similar structure to our locations .

Let's skip ahead and once again update our schema agreement checklist. We'll mark off the that have been added to our reviews so far.

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

Remember, we'll leave the three (Location.reviewsForLocation, Location.overallRating and Review.location) alone for now, but we'll get to them later on in the course!

✏️ Starting up the subgraph servers

Let's get these up and running. First, the locations .

  1. From the command line, navigate to the subgraph-locations directory:

    cd subgraph-locations

  2. Start the locations server by running the following command:

    npm start

  3. You should see a success message like the one below:

    🚀 Subgraph locations running at http://localhost:4001/

    Before we hop on over to check out our , let's rename this terminal window to subgraph-locations, to make it easier to come back to our running server later.

  4. In a web browser, go to http://localhost:4001 to open your server in Apollo Sandbox. Let's test that the locations server is working correctly by running the following :

    query GetAllLocations {
      locations {
        id
        name
        description
        photo
      }
    }

    When we run this , we can see that the locations server sends back our data correctly, perfect!

Task!

Now let's start up the reviews , which will follow similar steps!

  1. Open a new terminal window, and navigate to the subgraph-reviews directory:

    cd subgraph-reviews

  2. Start the reviews server by running the following command:

    npm start

  3. You should see a success message like the one below:

    🚀 Subgraph reviews running at http://localhost:4002/

Let's also rename this terminal window to be subgraph-reviews to make it easy to find again later.

  1. Open another browser tab to http://localhost:4002 and your server using Sandbox.

  2. We'll test that the reviews server is working correctly by running the following :

    query GetLatestReviews {
      latestReviews {
        id
        comment
        rating
      }
    }

    And we get back data. Huzzah!

Task!

Converting to subgraph servers

So far, our locations and reviews servers are just regular ol' , but we're about to convert them into Official !

This requires two steps:

  • Adding a Federation 2 definition to our files
  • Updating our ApolloServer instances

✏️ Federation 2 definition

Let's tackle the locations first.

Open up the locations.graphql file, and paste in this Federation 2 definition at the top of the file:

subgraph-locations/locations.graphql
extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.7",
        import: ["@key"])

This lets us opt into the latest features of . It also lets us import the various we'd like to use within our schema file (like the @key , shown above). We'll cover the @key later, so don't worry too much about this syntax now.

If your terminal is showing errors at this point, don't worry. Those will go away after we finish up the next step.

Task!

✏️ Updating our ApolloServer instance

The next step is to update our ApolloServer implementation.

Let's start with the locations server:

  1. In a new terminal window, navigate to the subgraph-locations directory.

  2. Run the following command to install the @apollo/subgraph package. (This will add @apollo/subgraph to the package.json file and node_modules directory.)

    npm install @apollo/subgraph

  3. Open the subgraph-locations/index.js file in a code editor. Import the buildSubgraphSchema function from @apollo/subgraph.

    subgraph-locations/index.js
    const { ApolloServer } = require("@apollo/server");
    const { startStandaloneServer } = require("@apollo/server/standalone");
    const { buildSubgraphSchema } = require("@apollo/subgraph");

  4. Down below, where we initialized the ApolloServer, we're now going to pass the existing typeDefs and resolvers properties as an object into the buildSubgraphSchema function.

    Then we'll use the result to set a new ApolloServer configuration property called schema.

    subgraph-locations/index.js
    const server = new ApolloServer({
      schema: buildSubgraphSchema({ typeDefs, resolvers }), 
    });

What's going on with the buildSubgraphSchema function?

The buildSubgraphSchema function takes an object containing typeDefs and resolvers and returns a federation-ready . This schema includes a number of federation directives and types that enable our to take full advantage of the power of federation. More on that in a bit!

  1. When we save our changes to the server file, the locally running locations server should restart automatically. Now let's check that everything is working correctly! Let's go back to our browser window with Apollo Sandbox at http://localhost:4001.

  2. Under the Query root type, we should see a new , _service. This is one of the federation-specific that buildSubgraphSchema adds to the . The uses this to access the string for your . We won't use this field directly, but seeing it appear in the Explorer tells us that our subgraph is running correctly.

http://localhost:4001
The new _service field appearing under the Query type

Now that we've set up the locations , it's time to repeat the process for the reviews ! Just follow the same flow as before. You got this.

Hint: If you get stuck, you can always check the final directory for a hint.

Set up the reviews subgraph

Practice

Drag 'n' Drop
To make an ApolloServer instance a subgraph, we install a package called 
 
. From that package, we use a function called 
 
, which accepts an object containing 
 
 and 
 
, and returns a federation-ready
 
. We add this to the ApolloServer configuration object using the 
 
 property.

Drag items from this box to the blanks above

  • dataSources

  • fields

  • router

  • subgraph schema

  • @apollo/server

  • schema

  • typeDefs

  • buildSupergraph

  • buildSubgraphSchema

  • resolvers

  • @apollo/subgraph

  • @apollo/federation

Key takeaways

  • Adding a Federation 2 definition to the top of our schema file lets us opt in to the latest features available in 2.
  • To make an ApolloServer instance a federation-ready , use the buildSubgraphSchema function from the @apollo/subgraph package.

Up next

We've got our up and running! But that's only the first piece of our architecture.

In the next lesson, we'll take a closer look at how we can use to pull all the pieces of our together.

Share your questions and comments about this lesson

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.