Federation 2 quickstart

Hello! This tutorial gets you up and running with Apollo Federation 2. It currently requires Node.js version 12 or 14.

Federation concepts

Before we start setting up our project, let's quickly cover what Apollo Federation is.

In a federated architecture, multiple GraphQL APIs are composed into a single federated graph. The individual APIs are called subgraphs, and they're composed into a supergraph:

Usually, each subgraph corresponds to a different service in your backend. The supergraph is then represented by a gateway, which routes each incoming query to the appropriate combination of subgraphs and returns the combined result.

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

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

Supergraph schema composition

As a best practice, the gateway does not compose its own supergraph schema. Instead, a separate process composes the schema and provides it to the gateway. This helps improve reliability and reduce downtime when you make changes to a subgraph.

There are multiple ways to compose a supergraph schema from subgraph schemas:

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

Using managed federation is strongly recommended for production environments. Meanwhile, composing with Rover 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 subgraphs for an example application: a Products subgraph and a Reviews subgraph. Here are their schemas for reference:

1
type Product @key(fields: "id") {
2
  id: ID!
3
  title: String
4
  url: String
5
  description: String
6
  price: Price
7
  salesRank(category: ProductCategory = ALL): Int
8
  salesRankOverall: Int
9
  salesRankInCategory: Int
10
  category: ProductCategory
11
  images(size: Int = 1000): [String]
12
  primaryImage(size: Int = 1000): String
13
}
14

15
type Price {
16
  cost: Money
17

18
  """A number between 0 and 1 signifying the % discount"""
19
  deal: Float
20
  dealSavings: Money
21
}
22

23
type Department {
24
  category: ProductCategory
25
  url: String
26
}
27

28
enum ProductCategory {
29
  ALL
30
  GIFT_CARDS
31
  ELECTRONICS
32
  CAMERA_N_PHOTO
33
  VIDEO_GAMES
34
  BOOKS
35
  CLOTHING
36
}
37

38
type Money {
39
  amount: Float
40
  currencyCode: CURRENCY_CODE
41
}
42

43
enum CURRENCY_CODE {
44
  USD
45
  EUR
46
}
47

48
type Query {
49
  bestSellers(category: ProductCategory = ALL): [Product]
50
  categories: [Department]
51
  product(id: ID!): Product
52
}

1
type Review @key(fields: "id") {
2
  id: ID!
3
  rating: Float
4
  content: String
5
}
6

7
type ReviewSummary {
8
  totalReviews: Int
9
  averageRating: Float
10
}
11

12
type Product @key(fields: "id") {
13
  id: ID! @external
14
  reviews: [Review]
15
  reviewSummary: ReviewSummary
16
}

1. Install the Rover CLI

Rover is Apollo's CLI for managing graphs, including federated ones. We'll use it throughout this quickstart.

Core binary

Install the core Rover binary with the appropriate command for your system:

1
curl -sSL https://rover.apollo.dev/nix/latest | sh

1
iwr 'https://rover.apollo.dev/win/latest' | iex

Federation 2 plugin

To use Federation 2 schema composition, you also need to install Rover's Federation 2 plugin:

1
curl https://rover.apollo.dev/plugins/rover-fed2/nix/latest | sh

1
iwr https://rover.apollo.dev/plugins/rover-fed2/win/latest | iex

After installing, run rover in your terminal with no arguments to confirm that it installed successfully.

2. Create a new gateway project

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

With the help of the @apollo/gateway library, Apollo Server will act as our federated gateway.

On your development machine, first create a new project directory for your Node.js gateway. Then inside that directory, run the following to create a package.json file:

1
npm init

Next, install the following required libraries:

1
npm install apollo-server @apollo/gateway@latest-2 graphql

Finally, create a file named index.js and paste the following into it as a minimal (not-yet-functional) gateway implementation:

1
const { ApolloServer } = require('apollo-server');
2
const { ApolloGateway } = require('@apollo/gateway');
3

4
const gateway = new ApolloGateway();
5

6
const server = new ApolloServer({
7
  gateway,
8
  // Subscriptions are not currently supported in Apollo Federation
9
  subscriptions: false
10
});
11

12
server.listen().then(({ url }) => {
13
  console.log(`🚀 Gateway ready at ${url}`);
14
}).catch(err => {console.error(err)});

This code demonstrates the necessary steps for creating a gateway:

1. We initialize an ApolloGateway instance.

2. We initialize an ApolloServer instance and pass it our gateway via the gateway option.

3. We call listen on our server instance to begin listening for incoming requests.

If we run this code as-is with node index.js, we get an error:

1
Error: When a manual configuration is not provided, gateway requires an Apollo configuration.

That's because we aren't currently providing a supergraph schema to our gateway! We'll fix that soon.

3. Obtain your subgraph schemas

To compose our supergraph schema, Apollo Studio needs the following information about each of our subgraphs:

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

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 products.graphql and paste the following schema into it:

   Products

   products.graphql

   1
   type Product @key(fields: "id") {
   2
     id: ID!
   3
     title: String
   4
     url: String
   5
     description: String
   6
     price: Price
   7
     salesRank(category: ProductCategory = ALL): Int
   8
     salesRankOverall: Int
   9
     salesRankInCategory: Int
   10
     category: ProductCategory
   11
     images(size: Int = 1000): [String]
   12
     primaryImage(size: Int = 1000): String
   13
   }
   14
   
   15
   type Price {
   16
     cost: Money
   17
   
   18
     """A number between 0 and 1 signifying the % discount"""
   19
     deal: Float
   20
     dealSavings: Money
   21
   }
   22
   
   23
   type Department {
   24
     category: ProductCategory
   25
     url: String
   26
   }
   27
   
   28
   enum ProductCategory {
   29
     ALL
   30
     GIFT_CARDS
   31
     ELECTRONICS
   32
     CAMERA_N_PHOTO
   33
     VIDEO_GAMES
   34
     BOOKS
   35
     CLOTHING
   36
   }
   37
   
   38
   type Money {
   39
     amount: Float
   40
     currencyCode: CURRENCY_CODE
   41
   }
   42
   
   43
   enum CURRENCY_CODE {
   44
     USD
   45
     EUR
   46
   }
   47
   
   48
   type Query {
   49
     bestSellers(category: ProductCategory = ALL): [Product]
   50
     categories: [Department]
   51
     product(id: ID!): Product
   52
   }

   Copy

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

   Reviews

   reviews.graphql

   1
   type Review @key(fields: "id") {
   2
     id: ID!
   3
     rating: Float
   4
     content: String
   5
   }
   6
   
   7
   type ReviewSummary {
   8
     totalReviews: Int
   9
     averageRating: Float
   10
   }
   11
   
   12
   type Product @key(fields: "id") {
   13
     id: ID!
   14
     reviews: [Review]
   15
     reviewSummary: ReviewSummary
   16
   }

   Copy

4. Sign up for Apollo Studio

Before we can compose our supergraph schema with Apollo Studio, we need a Studio account! Let's create one if you don't have one yet.

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

5. Authenticate Rover with Studio

We're going to use the Rover CLI to publish our subgraph schemas to Studio. In order to do that, we first need to authenticate Rover with Studio.

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

Our gateway project is ready, we've installed Rover, and we have a Studio account! Next, we'll start composing our supergraph schema in Studio.