1. Introducing the supergraph and GraphOS


Want to take your GraphQL API to the next level? Then you're in the right place!

If you've built products and experiences powered by a GraphQL API, then you know how powerful GraphQL can be when it comes to app development! You've felt that satisfaction of querying for exactly what you need and getting that data back in the shape you asked for. You understand the value of the acting as the contract between front-end and back-end. You recognize the efficiency of bringing together multiple s and services to be accessible under one endpoint.

Note: If this doesn't sound like you, you can start learning how to build a full-stack app with GraphQL through our introductory tutorial series, Lift-off.

So what's next? There comes the need to grow and evolve the graph. We want to deliver a richer experience, which involves adding more s, more features, more services. How do we protect our graph and facilitate its growth in a way that sets us up for success?

Enter Apollo .

Apollo GraphOS is a complete cloud platform for building, managing, and scaling your GraphQL API. provides a set of tools and services so that developers can focus on building better apps, faster.

We'll start with an existing GraphQL API and transform it into a (and we'll cover exactly what that means in this course).

Learner pre-requisites

We assume that you have a basic level of understanding of GraphQL and how to write a GraphQL query. Check out our Lift-off series if you need a refresher. You don't need to know any particular programming language for this tutorial.

Series overview

We're here to help you navigate the world of Apollo ! In this introductory series all about , we'll learn:

  • Basics: how to get started with GraphOS using an existing GraphQL API. That's the course you're in now!
  • Shipping your supergraph: how to ship supergraph changes using safe schema delivery
  • Growing your supergraph: how to add new capabilities and data to your supergraph
  • Securing your supergraph (coming soon): how to implement authentication and authorization in a supergraph
  • Improving your supergraph performance (coming soon): how to use caching and queries to make your supergraph faster

There's a lot to unpack! In this course, let's focus on that first important step: getting our GraphQL API on .

Along the way, we'll learn about the components of a architecture. We have lots of hands-on opportunities ahead: we'll build queries for the with the Apollo IDE, analyze our metrics, and configure the cloud .

Let's dive in!

In this lesson, we will:

  • Examine our API so far and our future plans 🍲🥘
  • Learn what GraphOS offers to help make app development easier and faster

Our API so far...

Introducing Poetic Plates 🍽️, the GraphQL API for adventurous cooks and foodies! Try your hand at AI-generated recipes with poetic instructions and delicious (or disastrous) results. With extremely detailed and sometimes helpful instructions, cooking has never been more fun!

Poetic Plates API title

The API architecture

The Poetic Plates API is written in JavaScript and uses Apollo Server. Here's what the codebase directory looks like:

📦 poetic-plates-api
┣ 📂 src
┃ ┣ 📂 datasources
┃ ┣ 📂 resolvers
┃ ┣ 📄 index.js
┣ 📄 package.json
┣ 📄 schema.graphql
┗ 📄 README.md

If you've built GraphQL APIs before, this should look familiar! It's a GraphQL server with a , s and s. Here's the quick rundown for the important files:

  • schema.graphql: A schema that defines the types and fields that describe our recipes content.
  • resolvers: Defines resolver functions for the fields in the schema.
  • datasources: In a real-world application, this data source would probably connect to a REST API or a database, but we're in tutorial-land so we're using hard-coded data in a JSON file in the same directory.
  • index.js: Creates an ApolloServer instance that uses the three components above.

You don't need to clone the repository, but feel free to browse the codebase if you're curious.

Poetic Plates is hosted at https://poetic-plates-recipes-api.herokuapp.com/, ready to receive queries and return data! To try it out, open up a new terminal and paste the curl command below.

curl --request POST \
--header 'content-type: application/json' \
--url 'https://poetic-plates-recipes-api.herokuapp.com/' \
--data '{"query":"query GetRandomRecipe {\n randomRecipe {\n name\n readyTime\n servings\n ingredients {\n text\n }\n }\n}"}'

You should get back an object: a random recipe with data about how long it takes to cook and the ingredients it needs!

How we're using Poetic Plates

Right now, the API is simply a small collection of recipes. We can do things like:

  • ask it for a random recipe
  • ask it a 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

But we've got big plans for Poetic Plates! We can see a future where we add new features like enabling users to add their own recipes, creating collections, sharing their thoughts about specific recipes. Maybe we can provide folks with more details about their ingredients, or we can recommend specific recipes based on what's already in their pantry. The possibilities are endless!

While we're working on these new features and growing our , we also want to keep our current functionality up and running smoothly. We want to track the health of our API, and monitor things like which s aren't being used, what are the most requested s, or which parts of a query are way too slow. What's causing problems for the clients using it? Where can we improve?

helps us solve these problems and more!

Introducing GraphOS

Apollo is a complete cloud platform for building, managing, and scaling a .

We'll learn about and make use of awesome features throughout this course and series, like:

  • The schema registry: A version control system for our , enabling us to see how our has evolved over time.

  • Tracking our supergraph's health and analytics: We'll examine how our s are being used, what queries clients are sending and what errors are occurring in our .

  • Safe schema delivery: checks every change to make sure it won't break our .

  • Cloud routing: takes care of provisioning and hosting the , a key part of our architecture. We'll learn more about what this means and see it in action over the next few lessons!

There are three ways to interface with :

  1. Apollo Studio - the web interface located at https://studio.apollographql.com/.
  2. The Rover CLI - a command-line interface that can run helpful commands in your local terminal or your CI/CD pipeline.
  3. The Platform API - a GraphQL API that enables you to perform GraphOS actions from your own custom application.

In this course, we'll primarily be working with Apollo Studio, so you'll need an account to follow along!

Creating an Apollo Studio account

In case you haven't created your Apollo account yet, visit http://studio.apollographql.com and click Create an account. You can sign up either with an email and password, or with an existing GitHub account. You'll also create your own organization.

After that, you're all set to use .


Key takeaways

  • Apollo GraphOS helps you build, manage and scale your GraphQL API.
  • There are three ways to interface with GraphOS: Studio, Rover and the Platform API.
  • In this tutorial, we'll be working with an existing API called Poetic Plates 🍽️, the GraphQL API for adventurous cooks and foodies!

Up next

Setting up our Poetic Plates API with is a pretty quick and easy process, as we'll see in lesson 3. But if you're still not really sure how it all works, what is going to do with the API, and how a fits into all this, then let's take a moment to answer those questions! In the next lesson, we'll identify the key pieces of a architecture and how helps to make it easier to maintain.


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.