1. Growing our supergraph


Have you already embarked on your journey?

You might have started from simple beginnings: a single subgraph and a -hosted . You've felt that satisfaction of querying for exactly what you need, getting that data back in the shape you asked for, and even deferred parts of a query that were slower than others. You've made a couple small changes, tweaking the to better suit your users' needs based on their feedback.

Now, you're excited to grow your and build on the modular architecture that the is known for.

Welcome, you've come to the perfect tutorial!

In this course, we're expanding our . We'll add another subgraph and learn how the creates and uses a query plan to resolve a query across multiple subgraphs. We'll also get hands-on with local development using Rover and the rover dev command. Along the way, we'll get to explore more features that help us build, maintain, and manage our .

This is the third course in this introductory series all about . You don't need to take the other courses in the series if you're already familiar with the material. Check out the learner prerequisites below to evaluate if you're ready for this course.

Learner prerequisites

You'll need to have:

  • A GitHub account and a code editor (we use VS Code), if you want to follow along with the course project.
  • An Apollo account. If you don't have one, you can sign up here.

You'll need to know:

  • GraphQL basics (working with a schema, writing resolvers)
  • Supergraph architecture basics (what a router and subgraphs are and how they work together)
  • Working with the terminal (navigating directories, running commands)
  • Git basics (commiting changes, pushing to a remote repository)

We'll be working with JavaScript to make changes to our subgraph server, but you won't need extensive knowledge to follow along with the course project.

The Poetic Plates supergraph 🍽️

Poetic Plates API title

Poetic Plates 🍽️ is the GraphQL API for adventurous cooks and foodies! Right now, it provides AI-generated recipes with poetic instructions and delicious (or disastrous) results. With extremely detailed and sometimes helpful instructions, cooking has never been more fun!

In GraphOS: Basics, we transformed the Poetic Plates API into a architecture.

Diagram of a supergraph architecture for Poetic Plates. The router points to a subgraph server labeled recipes.

A supergraph is a modular architecture consisting of a and one or more subgraphs. Poetic Plates currently has one subgraph called recipes. It also uses the cloud-hosted .

Right now, the Poetic Plates helps us do things like:

  • ask it for a random recipe
  • ask it for the full list of recipes in its database
  • ask it for the most recently added recipes
  • see a recipe's ingredients, cooking time, instructions, and more

In this course, we're going to add new capabilities to the . Specifically, we're adding information about kitchenware: the pots, pans, and kitchen utensils needed to bring a recipe to life. We have interesting information about what each piece of kitchen equipment looks like (for the cooking newbies out there) and how to clean them properly. And of course, all of this information will be delivered in poetic style ✍️

We're pretty excited to learn more about this kitchenware space and how to add it to our ! Let's get the project setup out of the way so we can dive in!

Project setup

If you've already completed GraphOS: Basics and GraphOS: Shipping your supergraph after May 24, 2023, you're all set! You can skip this section and jump to the end of the lesson to check off the tasks.

If you completed the courses before May 24, 2023, you'll need to update the recipes subgraph with new data. Expand the collapsible below to find your additional instructions. Then, skip ahead to the end of the lesson to check off the tasks.

If you haven't completed either of the courses, the rest of this section walks through a quickstart. You'll need to:

  • Deploy the recipes subgraph
  • Clone the recipes subgraph
  • Create a cloud supergraph on GraphOS
  • Install and authenticate Rover

Deploy the recipes subgraph

To get started, click the button below ⬇️

Deploy on Railway

Then, walk through the deploy setup steps on Railway. Feel free to use a different hosting platform of your choice!

You should now have a URL where your recipes subgraph server is available.

Clone the repository

Next, we'll clone a copy of the recipes subgraph to our own machine. This should be connected to the deployed URL, such that any commits you make to the main branch of your repo will be reflected in the deploy.

If you're using Railway, this will be taken care of for you. If you're using a different platform of your choice, you may need to do some additional steps.

Create a cloud supergraph

You'll need a cloud on . The recipes subgraph you cloned and deployed previously will act as the first subgraph of the .

Install and authenticate Rover

Rover is Apollo's command line interface (CLI) tool that helps developers work with graphs and interact with . It's a handy and versatile tool that can be used for both local development and CI/CD. We can use it to run checks, publish s to the , and much more.

Project setup checklist

Got everything you need?

Key takeaways

  • The supergraph architecture is composed of one or more subgraphs and a router.
  • GraphOS provisions and hosts the router, which is an instance of the Apollo Router. When GraphOS hosts the router, it's also called the cloud router.
  • Rover is Apollo's command line interface (CLI) tool that helps developers work with graphs and interact with GraphOS.

Up next

Ready to spice up our supergraph with a fresh new subgraph? Let's get cooking! 🥘


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.