3. What's in a supergraph?


Let's dive into the architecture of a .

In this lesson, we will:

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

Starting from a GraphQL API

First, let's take a look at how a GraphQL API currently works.

A GraphQL server receives requests from clients and resolves them

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!

This setup works well for smaller projects or teams, but what happens as our API grows? As more teams start adding types, s, and features to our , our API becomes harder to manage, scale, and deploy. This is a common bottleneck problem with monolithic backend services.

To solve this problem, we can divide our API's capabilities across multiple GraphQL-powered microservices, with each one taking responsibility for a different part of our API's . When we adopt this federated architecture, each of our microservices is called a subgraph, and together, they form the foundation of our supergraph.

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

In our case, the Poetic Plates API can become the very first in our . It takes responsibility for all of the 's types and s about our recipes.

As our grows, it can include one, two, or even two hundred s! It all depends on how we want to divide our features and capabilities to help our teams build and collaborate. So our big dreams for Poetic Plates will involve more subgraphs in the future!

This brings us to an important question: If we split our API's capabilities between lots of different microservices, how do clients query across all of them? For that, we need the other piece of our : the router.

The knows about all of our s, and it also knows which subgraph is responsible for each in our API's . Clients send queries to the router, and the router intelligently divides them up across the appropriate subgraphs.

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

The acts as the single access point for our API, kind of like an API gateway. This means that clients don't need to worry about communicating with our individual s!

Where GraphOS fits in

So that's the ! GraphOS is the developer platform that helps us build and manage it.

will provision, host and maintain the for us, which is really handy. If you want to host the router yourself, you can do that too! You can check out the Apollo documentation on how to do so.

On the other hand, we're responsible for hosting our s. We can use any hosting platform that suits our needs.

We'll provide with the URL and of our existing GraphQL API, which then becomes the first in our . Once it's on GraphOS, we'll get access to awesome features like the , observability metrics, safe schema delivery and more.


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 architecture is composed of one or more s and a .
  • The client sends a GraphQL to the . The router receives this request, figures out which s 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.
  • provisions and hosts the , which is an instance of the Apollo Router. When GraphOS hosts the router, it's also called the cloud router.

Up next

Grab your coding aprons, it's time to cook up a .


Share your questions and comments about this lesson

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.