1. Growing our supergraph


Have you already embarked on your journey?

You might have started from simple beginnings: a single and a -hosted . You've felt that satisfaction of 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 schema 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 supergraph is known for.

Welcome, you've come to the perfect tutorial!

In this course, we're expanding our . We'll add another and learn how the creates and uses a to resolve a query across multiple subgraphs. We'll also get hands-on with local development using 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:

  • basics (working with a schema, writing )
  • architecture basics (what a and 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 , 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 . Poetic Plates currently has one subgraph called recipes. It also uses the -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: Safe API delivery 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 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
  • Clone the recipes
  • Create a cloud on
  • Install and authenticate

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 is available.

Clone the repository

Next, we'll clone a copy of the recipes 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 you cloned and deployed previously will act as the first subgraph of the .

Install and authenticate Rover

is Apollo's command line interface (CLI) tool that helps developers work with 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 schemas to the schema registry, and much more.

Project setup checklist

Got everything you need?

Key takeaways

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

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.