Launch GraphOS Studio
You're viewing documentation for a previous version of this software. Switch to the latest stable version.

Federation quickstart

Part 2 - Composition in Apollo Studio

Back in Part 1, we created a federated gateway and used the CLI to compose a for it based on two s. Next, we'll move that composition process into the cloud.

Our gateway currently loads its composed from a file on startup. This means that whenever the schema changes, the gateway needs to restart to load the new version.

We can avoid this downtime by instead composing our with managed federation, a free cloud-based service that's part of Apollo Studio.

Managed federation basics

With managed federation, each of our s registers its with Apollo. Whenever a subgraph schema changes, Apollo composes a new schema.

Registers schema
Registers schema
Composes supergraph schema
Products subgraph
Reviews subgraph
Apollo Schema Registry

Whenever composition succeeds, Apollo pushes an updated to the uplink, a special endpoint that gateways use to fetch their configuration:

Updates config
Apollo Schema Registry
Apollo Uplink

Meanwhile, our gateway regularly polls the uplink for changes to its :

Polls for changes
Downloads changes
Apollo Uplink

Whenever an update is available, the gateway downloads it and automatically begins using the new , without requiring a restart.

We strongly recommended managed federation for reducing downtime in your production . Let's set it up!

1. Sign up for Apollo Studio

If you don't have an Apollo Studio account yet, let's create one.

Complete the first two steps of Get started with Apollo Studio (Create your account and Create your first graph), then return here.

For future steps, you'll need the name of the graph you just created in Apollo Studio. Make sure to have it available.

2. Authenticate Rover with Apollo Studio

The CLI includes commands for registering and fetching s from Apollo. To use these commands, you need to authenticate Rover with Apollo Studio.

Complete the first two steps of Configuring Rover (Obtain an API key and Provide the API key to Rover), then return here.

3. Register subgraph schemas

Let's return to our Node.js project. We can now use 's subgraph publish command to register our s with Apollo.

Run the following from your project directory, substituting your Studio graph's name where indicated:

rover subgraph publish <GRAPH_NAME> \
--routing-url \
--schema ./products.graphql \
--name products

Technically, you don't provide the graph's name, but rather its graph ref. Learn more.

If the command is successful, you'll see output like the following:

A new subgraph called 'products' for the 'docs-example-graph' graph was created
The gateway for the 'docs-example-graph' graph was updated with a new schema, composed from the updated 'products' subgraph

Nice! If you open your graph's details in Studio now, you'll see types and s from our products listed in the tab.

Now, let's do the same thing for our reviews service, again substituting your graph's name where indicated:

rover subgraph publish <GRAPH_NAME> \
--routing-url \
--schema ./reviews.graphql \
--name reviews

If you refresh the tab in Studio, you'll now see types and s from our reviews service as well.

Our has now been generated automatically by Apollo, but our gateway doesn't know how to poll for it yet. Let's tackle that next.

4. Authenticate the gateway with Apollo Studio

Right now in index.js, we're providing our to our ApolloGateway via the supergraphSdl option. We don't need to do this anymore!

Replace the contents of index.js with the following:

const { ApolloServer } = require('apollo-server');
const { ApolloGateway } = require('@apollo/gateway');
const gateway = new ApolloGateway();
const server = new ApolloServer({
server.listen().then(({ url }) => {
console.log(`🚀 Gateway ready at ${url}`);
}).catch(err => {console.error(err)});

So now, how do we connect and authenticate our gateway with Apollo Studio? With a graph API key that we set as the value of an environment variable.

API keys are secret credentials. Never share them outside your organization or commit them to version control. Delete and replace API keys that you believe are compromised.

  1. Obtain a graph API key for your Studio graph by following these steps. Copy its value.

    If you have an Enterprise plan, set the API key's role to Contributor.

  2. Create a new file named .env in your Node.js project folder.

  3. Paste the following into .env and replace YOUR_API_KEY with your graph API key:

  4. Add the dotenv Node.js library to your project:

    npm install dotenv

    This library takes care of reading environment values from your .env file.

  5. Add the following line to the very top of index.js:

  6. Start up your gateway with node index.js. You'll see some extra output now:

    No graph variant provided. Defaulting to `current`.
    🚀 Gateway ready at http://localhost:4000/
    Apollo usage reporting starting! See your graph at

By providing an API key to your gateway, you also automatically enable federated trace reporting to Apollo Studio, enabling you to view helpful performance metrics. Learn more about federated traces.

Now, open up Apollo Sandbox in your browser again. Sure enough, your 's types and s are all available, and you can execute test queries as before. But now, all of this information is coming from Apollo Studio.

Moving forward

Nice work! We have two subgraphs registering their s with Apollo, and we have a federated gateway that then fetches the composed supergraph schema.

If we were now to register changes to one of our s, our running gateway would automatically fetch the corresponding changes to the schema.

Next, let's look at how to apply what we've learned to our own services. Go to part 3.

Part 1 - Local schema composition
Part 3 - Working with subgraphs
Edit on GitHubEditForumsDiscord