Federation 2 quickstart

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

Federation concepts

Before we set 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 another service called a graph router, which routes each incoming query to the appropriate set of subgraphs and returns the combined result.

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

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

Supergraph schema composition

As a best practice, your router doesn't compose its own supergraph schema. 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 subgraph.

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

• Via managed federation in GraphOS 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 (named Locations and Reviews) from an imaginary space tourism application called FlyBy. Here are their URLs and schemas for reference:

1
extend schema
2
  @link(url: "https://specs.apollo.dev/federation/v2.0",
3
        import: ["@key"])
4

5
type Query {
6
  "The full list of locations presented by the Interplanetary Space Tourism department"
7
  locations: [Location!]!
8
  "The details of a specific location"
9
  location(id: ID!): Location
10
}
11

12
type Location @key(fields: "id"){
13
  id: ID!
14
  "The name of the location"
15
  name: String!
16
  "A short description about the location"
17
  description: String!
18
  "The location's main photo as a URL"
19
  photo: String!
20
}

1
extend schema
2
  @link(url: "https://specs.apollo.dev/federation/v2.0",
3
        import: ["@key"])
4

5
type Query {
6
  "The three latest reviews submitted for FlyBy's locations"
7
  latestReviews: [Review!]!
8
}
9

10
type Mutation {
11
  submitReview(locationReview: LocationReviewInput): SubmitReviewResponse
12
}
13

14
type Location @key(fields: "id") {
15
  id: ID!
16
  "The calculated overall rating based on all reviews"
17
  overallRating: Float
18
  "All submitted reviews about this location"
19
  reviewsForLocation: [Review]!
20
}
21

22
type Review {
23
  id: ID!
24
  "Written text"
25
  comment: String
26
  "A number from 1 - 5 with 1 being lowest and 5 being highest"
27
  rating: Int
28
  "The location the review is about"
29
  location: Location
30
}
31

32
input LocationReviewInput {
33
  "Written text"
34
  comment: String!
35
  "A number from 1 - 5 with 1 being lowest and 5 being highest"
36
  rating: Int!
37
  "Location Id"
38
  locationId: String!
39
}
40

41
type SubmitReviewResponse {
42
  "Similar to HTTP status code, represents the status of the mutation"
43
  code: Int!
44
  "Indicates whether the mutation was successful"
45
  success: Boolean!
46
  "Human-readable message for the UI"
47
  message: String!
48
  "Newly created review"
49
  locationReview: Review
50
}

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 supergraph
  • You don't need a paid Studio plan to complete this quickstart or use managed federation features.
• The Rover CLI, a command-line interface for interacting with graphs and their schemas

Let's set these up first!

Sign up for GraphOS Studio

Before we can use managed federation with GraphOS 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 GraphOS Studio (Create your account and Create your first graph), then return here.

Install the Rover CLI

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

Install the latest Rover release 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

After installing, run rover in your terminal with no arguments to confirm that it installed successfully. Verify that the printed version number matches the latest release (if it doesn't, you might need to manually delete a previous outdated installation).

Authenticate Rover with Studio

We'll use the Rover CLI to publish our subgraph schemas to Studio. 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.

2. Create a router project directory

As mentioned in Federation concepts, your federated supergraph is represented by a graph router 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 the Apollo Router in front of them.

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

1
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:

1
./router

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

1
Apollo Router v0.12.0 // (c) Apollo Graph, Inc. // Licensed as ELv2 (https://go.apollo.dev/elv2)
2

3
⚠️  The Apollo Router requires a composed supergraph schema at startup. ⚠️
4

5
👉 DO ONE:
6

7
  - Pass a local schema file with the '--supergraph' option:
8

9
      $ ./router --supergraph <file_path>
10

11
  - Fetch a registered schema from GraphOS Studio by setting
12
    these environment variables:
13

14
      $ APOLLO_KEY="..." APOLLO_GRAPH_REF="..." ./router
15

16
      For details, see the Apollo docs:
17
      https://www.apollographql.com/docs/router/managed-federation/setup
18

19
🔬 TESTING THINGS OUT?
20

21
  1. Download an example supergraph schema with Apollo-hosted subgraphs:
22

23
    $ curl -L https://supergraph.demo.starstuff.dev/ > starstuff.graphql
24

25
  2. Run the Apollo Router with the supergraph schema:
26

27
    $ ./router --supergraph starstuff.graphql

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

3. Obtain your subgraph schemas

To compose our supergraph schema, GraphOS 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 router)

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:

   Locations

   GraphQL

   locations.graphql

   1
   extend schema
   2
     @link(url: "https://specs.apollo.dev/federation/v2.0",
   3
           import: ["@key"])
   4
   
   5
   type Query {
   6
     "The full list of locations presented by the Interplanetary Space Tourism department"
   7
     locations: [Location!]!
   8
     "The details of a specific location"
   9
     location(id: ID!): Location
   10
   }
   11
   
   12
   type Location @key(fields: "id"){
   13
     id: ID!
   14
     "The name of the location"
   15
     name: String!
   16
     "A short description about the location"
   17
     description: String!
   18
     "The location's main photo as a URL"
   19
     photo: String!
   20
   }

   Copy

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

   Reviews

   GraphQL

   reviews.graphql

   1
   extend schema
   2
     @link(url: "https://specs.apollo.dev/federation/v2.0",
   3
           import: ["@key"])
   4
   
   5
   type Query {
   6
     "The three latest reviews submitted for FlyBy's locations"
   7
     latestReviews: [Review!]!
   8
   }
   9
   
   10
   type Mutation {
   11
     submitReview(locationReview: LocationReviewInput): SubmitReviewResponse
   12
   }
   13
   
   14
   type Location @key(fields: "id") {
   15
     id: ID!
   16
     "The calculated overall rating based on all reviews"
   17
     overallRating: Float
   18
     "All submitted reviews about this location"
   19
     reviewsForLocation: [Review]!
   20
   }
   21
   
   22
   type Review {
   23
     id: ID!
   24
     "Written text"
   25
     comment: String
   26
     "A number from 1 - 5 with 1 being lowest and 5 being highest"
   27
     rating: Int
   28
     "The location the review is about"
   29
     location: Location
   30
   }
   31
   
   32
   input LocationReviewInput {
   33
     "Written text"
   34
     comment: String!
   35
     "A number from 1 - 5 with 1 being lowest and 5 being highest"
   36
     rating: Int!
   37
     "Location Id"
   38
     locationId: String!
   39
   }
   40
   
   41
   type SubmitReviewResponse {
   42
     "Similar to HTTP status code, represents the status of the mutation"
   43
     code: Int!
   44
     "Indicates whether the mutation was successful"
   45
     success: Boolean!
   46
     "Human-readable message for the UI"
   47
     message: String!
   48
     "Newly created review"
   49
     locationReview: Review
   50
   }

   Copy

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