Apollo Router quickstart

Run the Apollo Router with Apollo-hosted subgraphs

Hello! This tutorial walks you through installing the Apollo Router and running it in front of some Apollo-hosted example subgraphs.

1. Download and extract the Apollo Router binary

Download options

Note: The Apollo Router is made available under the Elastic License v2.0 (ELv2). Read our licensing page for more details.

Automatic download (Linux, OSX, WSL)

If you have a bash-compatible terminal, you can download the latest version of the Apollo Router directly to your current directory with the following command:

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

Manual download

Go to the Apollo Router's GitHub Releases page and download the latest .tar.gz file that matches your system. Currently, tarballs are available for the following:

Linux (x86_64)
macOS (x86_64)
Windows (x86_64)

If a tarball for your system or architecture isn't available, you can build and run Apollo Router from source. You can also open an issue on GitHub for us to consider adding new architectures.

After downloading, extract the file by running the following from a new project directory, substituting the path to the tarball:

1
tar -xf path/to/file.tar.gz

Running the binary

You can now try running the Apollo Router from your project's root directory with the following command:

1
./dist/router

If you do, you'll get the following output:

1
APOLLO ROUTER <version>
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 Apollo 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

This is because Apollo Router requires a supergraph schema and we aren't providing it one! Let's fix that.

2. Download the example supergraph schema

For this quickstart, we're using example Apollo-hosted subgraphs, along with an example supergraph schema that's composed from those subgraph schemas.

From your project's root directory, run the following:

1
curl -sSL https://supergraph.demo.starstuff.dev/ > supergraph-schema.graphql

This saves a supergraph-schema.graphql file with the following contents:

supergraph-schema.graphql

1
schema
2
  @core(feature: "https://specs.apollo.dev/core/v0.1"),
3
  @core(feature: "https://specs.apollo.dev/join/v0.1")
4
{
5
  query: Query
6
  mutation: Mutation
7
}
8

9
directive @core(feature: String!) repeatable on SCHEMA
10

11
directive @join__field(graph: join__Graph, requires: join__FieldSet, provides: join__FieldSet) on FIELD_DEFINITION
12

13
directive @join__type(graph: join__Graph!, key: join__FieldSet) repeatable on OBJECT | INTERFACE
14

15
directive @join__owner(graph: join__Graph!) on OBJECT | INTERFACE
16

17
directive @join__graph(name: String!, url: String!) on ENUM_VALUE
18

19
scalar join__FieldSet
20

21
enum join__Graph {
22
  ACCOUNTS @join__graph(name: "accounts" url: "https://accounts.demo.starstuff.dev")
23
  INVENTORY @join__graph(name: "inventory" url: "https://inventory.demo.starstuff.dev")
24
  PRODUCTS @join__graph(name: "products" url: "https://products.demo.starstuff.dev")
25
  REVIEWS @join__graph(name: "reviews" url: "https://reviews.demo.starstuff.dev")
26
}
27

28
type Mutation {
29
  createProduct(name: String, upc: ID!): Product @join__field(graph: PRODUCTS)
30
  createReview(body: String, id: ID!, upc: ID!): Review @join__field(graph: REVIEWS)
31
}
32

33
type Product
34
  @join__owner(graph: PRODUCTS)
35
  @join__type(graph: PRODUCTS, key: "upc")
36
  @join__type(graph: INVENTORY, key: "upc")
37
  @join__type(graph: REVIEWS, key: "upc")
38
{
39
  inStock: Boolean @join__field(graph: INVENTORY)
40
  name: String @join__field(graph: PRODUCTS)
41
  price: Int @join__field(graph: PRODUCTS)
42
  reviews: [Review] @join__field(graph: REVIEWS)
43
  reviewsForAuthor(authorID: ID!): [Review] @join__field(graph: REVIEWS)
44
  shippingEstimate: Int @join__field(graph: INVENTORY, requires: "price weight")
45
  upc: String! @join__field(graph: PRODUCTS)
46
  weight: Int @join__field(graph: PRODUCTS)
47
}
48

49
type Query {
50
  me: User @join__field(graph: ACCOUNTS)
51
  topProducts(first: Int = 5): [Product] @join__field(graph: PRODUCTS)
52
}
53

54
type Review
55
  @join__owner(graph: REVIEWS)
56
  @join__type(graph: REVIEWS, key: "id")
57
{
58
  author: User @join__field(graph: REVIEWS, provides: "username")
59
  body: String @join__field(graph: REVIEWS)
60
  id: ID! @join__field(graph: REVIEWS)
61
  product: Product @join__field(graph: REVIEWS)
62
}
63

64
type User
65
  @join__owner(graph: ACCOUNTS)
66
  @join__type(graph: ACCOUNTS, key: "id")
67
  @join__type(graph: REVIEWS, key: "id")
68
{
69
  id: ID! @join__field(graph: ACCOUNTS)
70
  name: String @join__field(graph: ACCOUNTS)
71
  reviews: [Review] @join__field(graph: REVIEWS)
72
  username: String @join__field(graph: ACCOUNTS)
73
}

This file is all that Apollo Router needs to communicate with our subgraphs!

3. Run the router with the default configuration

Now from your project root, run the following:

1
./dist/router --supergraph supergraph-schema.graphql

The console output should look like the following:

1
2022-03-14T11:56:55.900207Z  INFO apollo_router: Starting Apollo Router
2
2022-03-14T11:56:56.000707Z  INFO apollo_router: Listening on http://127.0.0.1:4000 🚀

That's it! Visit http://127.0.0.1:4000 to open Apollo Sandbox. You can inspect the entire federated graph and run your first queries against the Apollo Router!

Next steps

Now that you know how to run Apollo Router with a supergraph schema, you can:

Set up managed federation
Learn about additional configuration options

Edit on GitHub

Introduction

Moving from @apollo/gateway