Docs
Launch GraphOS Studio

Federation 2 quickstart

Part 1 - Project setup


Hello! This tutorial gets you up and running quickly with an 2 .

💡 TIP

Related resources:

Federation concepts

Before we set up our project, let's quickly cover what is.

In a federated architecture, multiple APIs are

into a single federated . The individual APIs are called subgraphs, and they're composed into a supergraph:

Supergraph (A + B + C)
Subgraph A
Subgraph B
Subgraph C

Usually, each corresponds to a different service in your backend. The is then represented by another service called a graph router, which routes each incoming to the appropriate set of and returns the combined result.

The 's schema is the combination of each 's schema, plus some special federation-specific metadata.

This architecture enables clients to data from all simultaneously, just by querying the . It also enables different teams to own independent parts of a unified graph.

Supergraph schema composition

As a best practice, your doesn't compose its own . Instead, a separate process composes the schema and provides it to the router. This helps improve reliability and reduce downtime when you make changes to a .

There are multiple ways to compose a from :

  • Via managed federation in (we'll start with this)
  • On our local machine with the (we'll do this in
    Part 3
    )

Using is strongly recommended for production environments. Meanwhile, composing with can be useful for local development and CI environments.

Now that we have a high-level understanding of federation concepts, let's jump in!

Example subgraphs

This tutorial uses two Apollo-hosted (named Locations and Reviews) from an imaginary space tourism application called FlyBy. Here are their URLs and schemas for reference:

1. Set up Apollo tools

This quickstart uses a couple of Apollo tools to get the most out of federation:

  • GraphOS Studio, a cloud platform for monitoring, managing, and collaborating on your
    • You don't need a paid Studio plan to complete this quickstart or use features.
  • The Rover CLI, a command-line interface for interacting with and their schemas

Let's set these up first!

Sign up for GraphOS Studio

Before we can use with , we need a Studio account. Let's create one if you don't have one yet.

Complete the first two steps of

(Create your account and Create your first graph), then return here.

NOTE

  • Make sure the Studio you create is a that uses Federation 2!
  • For future steps, you'll need the ID of the you create. Make sure to have it available.

Install the Rover CLI

Rover is Apollo's CLI for managing all kinds of , including and . We'll use it throughout this quickstart.

NOTE

Even if you already have installed, you should update your version now by completing this step.

Install the latest release with the appropriate command for your system:

MacOS / Unix-like
curl -sSL https://rover.apollo.dev/nix/latest | sh
Windows
iwr 'https://rover.apollo.dev/win/latest' | iex

After installing, run rover in your terminal with no to confirm that it installed successfully. Verify that the printed version number matches the

(if it doesn't, you might need to manually delete a previous outdated installation).

Authenticate Rover with Studio

We'll use the to publish our to Studio. To do that, we first need to authenticate Rover with Studio.

Complete the first two steps of

(Obtain an API key and Provide the API key to Rover), then return here.

2. Create a router project directory

As mentioned in

, your federated is represented by a graph that routes queries to various . For this tutorial, we'll use some Apollo-hosted example services as our subgraphs, and we'll set up the in front of them.

NOTE

The is a high-performance, precompiled Rust executable that acts as the router for a .

Alternatively, can act as your , as documented in

. This tutorial uses the because it's the recommended default for all new (for details, see
Choosing a router library
).

On your development machine, first create a new directory for your project. Then inside that directory, run the following to install the :

curl -sSL https://router.apollo.dev/download/nix/latest | sh

This installs the router executable in your project directory. You can try running it with the following command:

./router

If you do, you'll get a startup error message like the following:

That's because we aren't currently providing a to the . We'll fix that soon.

3. Obtain your subgraph schemas

To compose our , needs the following information about each of our :

  • The 's schema
  • The URL of the 's endpoint (which must be accessible by the )

Fortunately, we have all of this information! Let's collect it in our project.

Do the following in your project's root directory:

  1. Create a new file called locations.graphql and paste the following schema into it:

  2. Create a new file called reviews.graphql and paste the following schema into it:

💡 TIP

In most federated , each lives in the codebase for its associated subgraph. Because we're using remotely hosted example subgraphs in this tutorial, we're saving these subgraph schemas in our project for convenience.


We have a Studio account, we've installed , and our project directory is ready. Next, we'll start

Previous
Introduction
Next
Composition in GraphOS Studio
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company