2. What's in a supergraph?


Let's dive into the architecture of a .

In this lesson, we will:

  • Identify the key pieces of a supergraph, what each piece does and where it's hosted
  • Describe how a round-trip request and response works from the client to the supergraph

Starting from a GraphQL API

Let's take a look at how a GraphQL API currently works.

When a client needs some data, it sends a GraphQL to the GraphQL server. The server uses its , s, and s to retrieve and resolve that data, then sends it back to the client. It's a pretty great experience!

A GraphQL server receives requests from clients and resolves them

In the previous lesson, we talked about using to help us get insight into our (and more!). All needs is an existing GraphQL API!

When we plug it into , our API is transformed into a .

What's in a supergraph?

A supergraph has a modular architecture, which means it's composed of one or more modules. A module has its own , s, and s. Sound familiar? It should, that's essentially a GraphQL server! Specifically, we call these modules by another name: subgraphs.

An illustration of two subgraphs, with each subgraph having its own schema file, resolvers and data sources.

A subgraph is usually focused on a specific business domain. In our case, the Poetic Plates API is one such module which is all about serving recipe content.

A can have many subgraphs; it all depends on your API's features and capabilities. We have big dreams for Poetic Plates involving more subgraphs in the future!

To query data from subgraphs, we need another key component: the .

The router is responsible for accepting incoming s from clients, figuring out which subgraphs can resolve which parts of the , and sending these smaller parts to the appropriate subgraphs.

The acts as the single endpoint that clients can send their queries to. Clients shouldn't have to worry about communicating with the subgraphs in a !

The journey of a GraphQL operation, in a supergraph with the router and subgraphs

And that's how things work in a !

Where GraphOS fits in

Remember, is the platform that lets us manage and scale our . To get started, we provide it with our existing GraphQL API, which becomes the first subgraph in our .

Behind the scenes, will provision, host and maintain the for us, which is really handy. Specifically, it'll create an instance of the Apollo , host it somewhere, then provide us with the URL endpoint that we can use to query it.

Because it's hosted on , it's also referred to as the cloud router. You might also hear the term cloud-hosted supergraph. Both refer to the same thing: takes care of hosting for us!

Note: We also have the option to self-host the Apollo ourselves, but we won't be covering how to do that in this tutorial. If you're interested in the self-hosting option, you can check out the Apollo documentation on how to do so.

On the other hand, we're responsible for hosting our subgraphs. We can use any hosting platform that suits our needs. For example, the Poetic Plates API is hosted on Heroku.


Which of the following are the responsibilities of a router in a supergraph architecture?
Which of the following are the responsibilities of a subgraph in a supergraph architecture?
Where should subgraph servers be hosted?

Key takeaways

  • The supergraph architecture is composed of one or more subgraphs and a router.
  • The client sends a GraphQL operation to the router. The router receives this request, figures out which subgraphs are responsible for resolving it, and sends the operations to the appropriate subgraphs. The subgraphs resolve the data and return it to the router, which then bundles it up to return to the client.
  • 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.

Up next

We're ready to transform our GraphQL API into a with the help of !


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.