Building out the subgraphs - GraphQL Tutorials

Overview

So now we have a plan for our subgraphs! 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 GraphQL servers into subgraphs.

Exploring the starter code

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

The `locations` subgraph

We'll start with the locations subgraph. 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 GraphQL server, not a subgraph.
locations.graphql: A schema that defines the types and fields owned by the locations subgraph.
resolvers.js: Defines resolver functions for the fields 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 fields that have been added to our locations subgraph 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 subgraph. The files in the subgraph-reviews directory have a similar structure to our locations subgraph.

Let's skip ahead and once again update our schema agreement checklist. We'll mark off the fields that have been added to our reviews subgraph 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 fields (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 subgraph servers up and running. First, the locations subgraph.

From the command line, navigate to the subgraph-locations directory:
cd subgraph-locations
Start the locations server by running the following command:
npm start
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 subgraph, let's rename this terminal window to subgraph-locations, to make it easier to come back to our running server later.
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:
query GetAllLocations {
locations {
id
name
description
photo
}
}
When we run this query, we can see that the locations server sends back our data correctly, perfect!

{
  "data": {
    "locations": [
      {
        "id": "loc-1",
        "name": "The Living Ocean of New Lemuria",
        "description": "Surviving is usually extremely difficult, especially when nutrients are scarce and you have to choose between growing or reproducing. One species on this planet has developed a nifty method to prepare for this. Once full matured, this species will split into 2 versions of itself and attached to each other, so it's essentially reproducing. Once those 2 are fully grown, they newly grown version will either detach itself if enough nutrients are available or it becomes a storage unit for the original, if nutrients are scarce. If nutrients continue to be scarce, the original will use slowly consume the nutrients in the new version in the hope that new nutrients become available again and it can repeat the cycle.",
        "photo": "https://res.cloudinary.com/apollographql/image/upload/v1644381344/odyssey/federation-course1/FlyBy%20illustrations/Landscape_4_lkmvlw.png"
      },
      {
        "id": "loc-2",
        "name": "Vinci",
        "description": "Many of the creatures on this planet have evolved into gliders, so to speak. Most of the fish and aquatic mammals, despite coming in various shapes and sizes, tend to glide through the water without effort, similar to how manta's glide on Earth. However, the surface species are more astonishing. Similar to the flying squirrels or the vultures of Earth, many of the species on this planet have developed ways to effortlessly move from one place to another by using the winds. But there is one species which shows signs of sentience. These species, a type of bird, love to play and have become masters of flight. Similar to how dolphins play, explore and learn, these species use their intellect and courage to play and sometimes challenge each other to death defying tricks.",
        "photo": "https://res.cloudinary.com/apollographql/image/upload/v1644381349/odyssey/federation-course1/FlyBy%20illustrations/Landscape_15_tiqel5.png"
      },
      {
        "id": "loc-3",
        "name": "Asteroid B-612",
        "description": "Nutrients are always needed but not always around, so organisms have to find ways to get them. Common ways are using different roots to find them in deep or shallow grounds or even stealing them from others, but on this planet many species have found a different balance. Unlike most plants on Earth who tend to only produce oxygen and nutrients, usually in the form of sugars, for itself, the organisms on this planet also produce other forms of nutrients for itself, usually for different purposes. These processes often lead to many byproducts which it doesn't need and are thus discarded. These discarded products are exactly what other species need to live and in turn produce byproducts it discards for the other organisms, leading to a delicate balance.",
        "photo": "https://res.cloudinary.com/apollographql/image/upload/v1644381343/odyssey/federation-course1/FlyBy%20illustrations/Landscape_6_vt6y3v.png"
      },
      {
        "id": "loc-4",
        "name": "Krypton",
        "description": "Similar to the surface, the underwater world has little more to offer than basic lifeforms. However, this planet has an astonishing water world. Almost everything is covered in a type of sea-grass. This grass varies in length depending on the region, but they're all part of the same species. But what's probably more surprising are the 'flowers' you'll find in these fields of sea-grass. These flowers can only be described as primitive soft corals, but they're neither coral nor plant.",
        "photo": "https://res.cloudinary.com/apollographql/image/upload/v1644381344/odyssey/federation-course1/FlyBy%20illustrations/Landscape_9_kbenjj.png"
      },
      {
        "id": "loc-5",
        "name": "Zenn-la",
        "description": "The plant-like organisms on this planet are made up of millions of flowers. Their combined colors and scents make for an amazing spectacle, but they leave little space for other species, which is why there are only very few bush and shrub species. Fungi, grasses and trees are non-existent.",
        "photo": "https://res.cloudinary.com/apollographql/image/upload/v1644381346/odyssey/federation-course1/FlyBy%20illustrations/Landscape_8_zd1e68.png"
      }
    ]
  }
}

Task!

I've started the locations server and can query it successfully in Apollo Sandbox.

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

Open a new terminal window, and navigate to the subgraph-reviews directory:
cd subgraph-reviews
Start the reviews server by running the following command:
npm start

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.

Open another browser tab to http://localhost:4002 and query your server using Sandbox.
We'll test that the reviews server is working correctly by running the following query:
query GetLatestReviews {
latestReviews {
id
comment
rating
}
}
And we get back data. Huzzah!

Task!

I've started the reviews server and can query it successfully in Apollo Sandbox.

Converting to subgraph servers

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

This requires two steps:

Adding a Federation 2 definition to our subgraph schema files
Updating our ApolloServer instances

✏️ Federation 2 definition

Let's tackle the locations subgraph 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.0",
        import: ["@key"])

This lets us opt into the latest features of Apollo Federation version 2. It also lets us import the various directives we'd like to use within our schema file (like the @key directive, shown above). We'll cover the @key directive 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!

I've added the Federation 2 definition to the top of the locations.graphql file.

✏️ Updating our `ApolloServer` instance

The next step is to update our ApolloServer implementation.

Let's start with the locations server:

In a new terminal window, navigate to the subgraph-locations directory.
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

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");

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 subgraph schema. This schema includes a number of federation directives and types that enable our subgraph to take full advantage of the power of federation. More on that in a bit!

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.
Under the Query root type, we should see a new field, _service. This is one of the federation-specific fields that buildSubgraphSchema adds to the subgraph. The router uses this field to access the SDL string for your subgraph schema. 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 subgraph, it's time to repeat the process for the reviews subgraph! 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.

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

fields
@apollo/server
schema
dataSources
subgraph schema
typeDefs
buildSubgraphSchema
router
@apollo/federation
resolvers
buildSupergraph
@apollo/subgraph

Key takeaways

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

Up next

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

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

Overview

Exploring the starter code

The locations subgraph

The reviews subgraph

✏️ Starting up the subgraph servers

Converting to subgraph servers

✏️ Federation 2 definition

✏️ Updating our ApolloServer instance

Practice

Key takeaways

Up next

The `locations` subgraph

The `reviews` subgraph

✏️ Updating our `ApolloServer` instance