Federation quickstart

Part 3 - Local composition

Back in Part 2, we used managed federation with Apollo Studio to compose our router's supergraph schema. Next, let's try out composing locally with the Rover CLI.

1. Provide subgraph details

Like Apollo Studio, the Rover CLI needs the following information about each of our subgraphs to compose them:

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

To provide these details to Rover, we define a YAML configuration file.

In your router project directory, create a file called supergraph-config.yaml and paste the following into it:

supergraph-config.yaml

1
federation_version: 2
2
subgraphs:
3
  locations:
4
    routing_url: https://flyby-locations-sub.herokuapp.com/
5
    schema:
6
      subgraph_url: https://flyby-locations-sub.herokuapp.com/
7
  reviews:
8
    routing_url: https://flyby-reviews-sub.herokuapp.com/
9
    schema:
10
      subgraph_url: https://flyby-reviews-sub.herokuapp.com/

As you can see, we're providing the same URL as the value of two different fields. These fields serve different purposes:

routing_url is the URL the router will use to send GraphQL operations to the subgraph at runtime.
schema.subgraph_url is the URL that Rover will use to fetch the subgraph schema for composition purposes.

These URLs might theoretically differ. The YAML file also supports providing a subgraph's schema as a local file path, or as a registered graph ref that Rover can fetch from Apollo (for details, see the Rover docs).

2. Perform composition

Now that our configuration file is ready, we can compose our supergraph schema. To do that, we'll use Rover's supergraph compose command.

Haven't installed the latest version of Rover?

From your project directory, run the following command in your terminal:

1
rover supergraph compose --config ./supergraph-config.yaml

⚠️ Important: The first time you run this command with a Federation 2 YAML configuration, Rover installs a separate plugin and prompts you to accept the terms and conditions of the ELv2 license.

To automatically accept this prompt (especially important for CI environments), add APOLLO_ELV2_LICENSE=accept to the beginning of the command.

Learn more about ELv2.

Rover outputs the following supergraph schema:

1
schema
2
  @link(url: "https://specs.apollo.dev/link/v1.0")
3
  @link(url: "https://specs.apollo.dev/join/v0.2", for: EXECUTION)
4
{
5
  query: Query
6
  mutation: Mutation
7
}
8

9
directive @join__field(graph: join__Graph!, requires: join__FieldSet, provides: join__FieldSet, type: String, external: Boolean, override: String, usedOverridden: Boolean) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION
10

11
directive @join__graph(name: String!, url: String!) on ENUM_VALUE
12

13
directive @join__implements(graph: join__Graph!, interface: String!) repeatable on OBJECT | INTERFACE
14

15
directive @join__type(graph: join__Graph!, key: join__FieldSet, extension: Boolean! = false, resolvable: Boolean! = true) repeatable on OBJECT | INTERFACE | UNION | ENUM | INPUT_OBJECT | SCALAR
16

17
directive @link(url: String, as: String, for: link__Purpose, import: [link__Import]) repeatable on SCHEMA
18

19
scalar join__FieldSet
20

21
enum join__Graph {
22
  LOCATIONS @join__graph(name: "locations", url: "https://flyby-locations-sub.herokuapp.com/")
23
  REVIEWS @join__graph(name: "reviews", url: "https://flyby-reviews-sub.herokuapp.com/")
24
}
25

26
scalar link__Import
27

28
enum link__Purpose {
29
  """
30
  `SECURITY` features provide metadata necessary to securely resolve fields.
31
  """
32
  SECURITY
33

34
  """
35
  `EXECUTION` features provide metadata necessary for operation execution.
36
  """
37
  EXECUTION
38
}
39

40
type Location
41
  @join__type(graph: LOCATIONS, key: "id")
42
  @join__type(graph: REVIEWS, key: "id")
43
{
44
  id: ID!
45

46
  """The name of the location"""
47
  name: String! @join__field(graph: LOCATIONS)
48

49
  """A short description about the location"""
50
  description: String! @join__field(graph: LOCATIONS)
51

52
  """The location's main photo as a URL"""
53
  photo: String! @join__field(graph: LOCATIONS)
54

55
  """The calculated overall rating based on all reviews"""
56
  overallRating: Float @join__field(graph: REVIEWS)
57

58
  """All submitted reviews about this location"""
59
  reviewsForLocation: [Review]! @join__field(graph: REVIEWS)
60
}
61

62
input LocationReviewInput
63
  @join__type(graph: REVIEWS)
64
{
65
  """Written text"""
66
  comment: String!
67

68
  """A number from 1 - 5 with 1 being lowest and 5 being highest"""
69
  rating: Int!
70

71
  """Location Id"""
72
  locationId: String!
73
}
74

75
type Mutation
76
  @join__type(graph: REVIEWS)
77
{
78
  submitReview(locationReview: LocationReviewInput): SubmitReviewResponse
79
}
80

81
type Query
82
  @join__type(graph: LOCATIONS)
83
  @join__type(graph: REVIEWS)
84
{
85
  """
86
  The full list of locations presented by the Interplanetary Space Tourism department
87
  """
88
  locations: [Location!]! @join__field(graph: LOCATIONS)
89

90
  """The details of a specific location"""
91
  location(id: ID!): Location @join__field(graph: LOCATIONS)
92

93
  """The three latest reviews submitted for FlyBy's locations"""
94
  latestReviews: [Review!]! @join__field(graph: REVIEWS)
95
}
96

97
type Review
98
  @join__type(graph: REVIEWS)
99
{
100
  id: ID!
101

102
  """Written text"""
103
  comment: String
104

105
  """A number from 1 - 5 with 1 being lowest and 5 being highest"""
106
  rating: Int
107

108
  """The location the review is about"""
109
  location: Location
110
}
111

112
type SubmitReviewResponse
113
  @join__type(graph: REVIEWS)
114
{
115
  """Similar to HTTP status code, represents the status of the mutation"""
116
  code: Int!
117

118
  """Indicates whether the mutation was successful"""
119
  success: Boolean!
120

121
  """Human-readable message for the UI"""
122
  message: String!
123

124
  """Newly created review"""
125
  locationReview: Review
126
}

As you can see, this composed schema includes all of the types and fields from our subgraph schemas, along with many additional directives that the router uses to route incoming operations.

Now, append > supergraph.graphql to the above command to write the composed schema to a file:

1
rover supergraph compose --config ./supergraph-config.yaml > supergraph.graphql

3. Provide the composed schema to the router

To provide a Rover-composed supergraph schema to our router, we pass it as a command-line option. Run the following in your router project directory:

1
./router --supergraph=supergraph.graphql

For brevity, we're skipping setting the APOLLO_KEY environment variable here. It isn't required if you provide your schema with --supergraph, however you do need to provide it to enable federated trace reporting.

This time, the router reads your static supergraph schema from a file. This does not communicate with Apollo Studio, which means it's well suited to local development or CI environments where you don't want to introduce an external dependency.

Learn more about router configuration options.

Great job! We've seen how to compose our supergraph schema with both managed federation and the Rover CLI. Next, let's look at how to apply what we've learned to our own subgraphs. Go to part 4.

Edit on GitHub

2️⃣ Composition in Apollo Studio

4️⃣ Working with subgraphs