1. Intro to federation

👋 Welcome to GraphQL Federation with .NET (C#) & Hot Chocolate!

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

If you've built products and experiences using , then you know just how powerful it can be! You've tasted that satisfaction of for exactly what you need and getting that data back in the shape you asked for. Plus, the ability to mix and blend multiple and services all under a single endpoint is so helpful!

So what's next? We might feel that hunger to grow and evolve our API. We want to serve up a richer experience, which means adding more ingredients: more , more services, more features, more capabilities. So how do we protect our API and facilitate its growth in a way that sets us up for success?

In this course, we'll learn about the components of what's called a supergraph, also known as a federated architecture. And we have lots of hands-on opportunities ahead of us, building new features on top of an existing GraphQL API. We'll use some of the primary components to ship these changes safely: , , and rover dev.

Let's jump in!

In this lesson, we will:

  • Identify the key pieces of a federated architecture
  • Set up our course project

Starting from a GraphQL API

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

A GraphQL server receives requests from clients and resolves them

When a client needs some data, it sends a to the . The server uses its schema, , and 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, , and features to our schema, our API becomes harder to manage, scale, and deploy. This is a common bottleneck problem with monolithic backend services.

Introducing federation

To solve this problem, we can divide our API's capabilities across multiple -powered microservices, with each one taking responsibility for a different part of our API's schema. 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.

As our grows, it can include one, two, or even two hundred ! It all depends on how we want to divide our features and capabilities to help our teams build and collaborate.

If we split our API's capabilities between lots of different microservices, how do clients across all of them? For that, we need the other piece of our : the router.

The knows about all of our , and it also knows which subgraph is responsible for each in our API's schema. 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. Because the router manages how requests are routed and resolved, clients don't need to worry about communicating with our individual !

Following this approach, we can grow our API to include numerous and services: with all of its capabilities unified behind a single, intelligent .

Why use federation?

With a architecture, nothing changes from the client perspective. They still communicate with a single endpoint (the ), and they don't need to know a thing about how the graph is built under the hood.

On the backend API-side, we have a clear separation of concerns. By splitting up our schema into , backend teams can work on their own subgraphs independently, without impacting developers working on other subgraphs. And since each subgraph is a separate server, teams have the flexibility to choose the language, infrastructure, and policies that work best for them.

What we're building

As we learn and practice these federation concepts, we'll be building our course project: MusicMatcher.

MusicMatcher is a music catalog app: a resource we can use to find the right soundtrack for the right moment. In this course, we're bringing our soundtrack recommendations into a common activity in our daily lives: cooking! Find the perfect playlist to listen to while you're spicing up your latest creation.

Mockup of MusicMatcher

We built the basics of this in the Intro to GraphQL course. This soundtracks server will become the first in our . It takes responsibility for all of the schema's types and about playlists and tracks.

Let's get everything ready to start building!

Project setup

To follow along with the course, you will need the following:

Prerequisite knowledge

This course uses C# and .NET 8. You should be familiar with C# basic programming concepts to follow along with this course.

We also recommend being familiar with the basics of and building a using the Hot Chocolate framework. We'll be using the annotation-based approach. If you need a refresher, check out the Intro to GraphQL course.

Note: We also offer this course in Java with DGS and TypeScript with Apollo Server.

Code editor or IDE

We'll be using VS Code but you can feel free to use your favorite editor or IDE for .NET development!

Clone the repo locally

The project repo is the end result of going through the Intro to GraphQL course, with additional configuration to enable federation.

We recommend starting fresh and cloning the repo below:

git clone https://github.com/apollographql-education/odyssey-federation-hotchocolate

Here's what the project looks like:

📦 Odyssey.MusicMatcher
┣ 📂 .config
┃ ┣ 📄 dotnet-tools.json
┣ 📂 Data
┃ ┣ 📄 SpotifyService.cs
┃ ┣ 📄 swagger.json
┣ 📂 Types
┃ ┣ 📄 AddItemsToPlaylistInput.cs
┃ ┣ 📄 AddItemsToPlaylistPayload
┃ ┣ 📄 Mutation.cs
┃ ┣ 📄 Playlist.cs
┃ ┣ 📄 Query.cs
┃ ┣ 📄 Track.cs
┣ 📂 Properties
┃ ┣ 📄 launchSettings.json
┣ 📂 Router
┃ ┣ 📄 router-config.yaml
┃ ┣ 📄 .env
┃ 📄 appsettings.Development.json
┃ 📄 appsettings.json
┃ 📄 Odyssey.MusicMatcher.csproj
┃ 📄 Odyssey.MusicMatcher.sln
┃ 📄 Program.cs
┗ 📄 README.md

To install dependencies, run:

dotnet build

Don't have .NET installed? Find your download link here. We're using .NET 8 for this course.

Then, check that the project can run successfully:

dotnet run

You should see:

Odyssey.MusicMatcher ❯ dotnet run
info: Microsoft.Hosting.Lifetime[14]
Now listening on: http://localhost:5059
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
Hosting environment: Development
info: Microsoft.Hosting.Lifetime[0]
Content root path: /Users/your-path/Odyssey.MusicMatcher

The project will be running on http://localhost:5059/graphql by default!


Sign up for an Apollo GraphOS account with an Enterprise plan

This course uses (more on this in the next lesson!), which requires an Apollo account with an . You can still follow along if your organization is on a different plan, but you won't be able to complete certain hands-on tasks. You can also test out this functionality by signing up for a free Enterprise trial.


Installing and authenticating the Rover CLI

is Apollo's command line interface (CLI) tool that helps developers work with and interact with .



Which of the following are benefits of using Apollo Federation?
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?

Key takeaways

  • Federation is an architecture for creating modular , also known as a architecture.
  • A is composed of one or more and the . A subgraph is a microservice responsible for its own domain. The router is the single endpoint that manages how requests are routed and executed, kind of like an API gateway.
  • The client sends a to the . The router receives this request, figures out which 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.

Up next

We'll learn about and how it can help us manage our .


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.