Overview

Have you already embarked on your supergraph journey?

You might have started from simple beginnings: a single subgraph and a GraphOS-hosted router. 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 schema to better suit your users' needs based on their feedback.

Now, you're excited to grow your supergraph 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 supergraph. We'll add another subgraph and learn how the router 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 GraphOS features that help us build, maintain, and manage our supergraph.

This is the third course in this introductory series all about GraphOS. 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 🍽️ 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 supergraph architecture.

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

Right now, the Poetic Plates supergraph 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 supergraph. 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 supergraph! 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 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 ⬇️

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 supergraph on GraphOS. The recipes subgraph you cloned and deployed previously will act as the first subgraph of the supergraph.

Install and authenticate Rover

Rover is Apollo's command line interface (CLI) tool that helps developers work with graphs and interact with GraphOS. 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

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! 🥘