Sending HTTP headers to subgraphs

Configure which headers the Apollo Router sends to which subgraphs

You can configure which HTTP headers the Apollo Router includes in its requests to each of your subgraphs. You can define per-subgraph header rules, along with rules that apply to all subgraphs.

You define header rules in your YAML configuration file, like so:

router.yaml

1
# ...other configuration...
2
headers:
3
  all: # Header rules for all subgraphs
4
    - propagate:
5
        matching: ^upstream-header-.*
6
    - remove:
7
        named: "x-legacy-account-id"
8
  subgraphs:
9
    products: # Header rules for just the products subgraph
10
    - insert:
11
        name: "router-subgraph-name"
12
        value: "products"

Supported header rules

The Apollo Router supports the following types of header rules:

`propagate`

Enables you to selectively pass along headers that were included in the client's request to the router.

You can specify which headers to propagate based on a matching regex pattern:

1
- propagate:
2
    matching: .*

Note: The Apollo Router never propagates so-called hop-by-hop headers (such as Content-Length) when propagating by pattern.

Alternatively, you can provide a static string via the named option. These named configurations have additional flexibility, because they support the following options:

default: A value to set if no value was sent by the client
rename: Renames the header's key to the provided value

1
- propagate:
2
      named: "x-user-id"
3
      default: "abc123"
4
      rename: "account-id"

`remove`

Enables you to selectively remove headers that were included in the client's request to the router. Like propagate, this option can match either a static string or a regular expression.

1
# Do not send this subgraph the "Cookie" header.
2
- remove:
3
    named: "Cookie"
4
- remove:
5
    # Remove headers that include the legacy 'x-' prefix.
6
    matching: ^x-.*$

`insert`

Enables you to add custom headers to requests going to a specific subgraph. These headers are always static strings that originate in the router, instead of originating in the client.

1
- insert:
2
    name: "sent-from-our-apollo-router"
3
    value: "indeed"

Rules Ordering

Rules are applied in the order in which they are declared. For example:

bad_configuration.yaml

1
headers:
2
all:
3
  - remove:
4
    named: "test"
5
  - propagate:
6
    matching: .*

In this example, the header named test would be removed from the propagation list, but then immediately the propagate rule would match and ensure it was added back to the list. This is clearly undesirable. To do this correctly, ensure that the propagate rule is specified first in your configuration:

good_configuration.yaml

1
headers:
2
all:
3
  - propagate:
4
    matching: .*
5
  - remove:
6
    named: "test"

This would result in adding all headers to the propagation list, then removing the header named "test", which is the desired outcome.

Example

Here's a complete example showing all the possible configuration options in use:

router.yaml

1
headers:
2
  # Header rules for all subgraphs
3
  all:
4
  # Propagate matching headers
5
  - propagate:
6
      matching: ^upstream-header-.*
7
  # Propagate matching headers
8
  - propagate:
9
      named: "some-header"
10
      default: "default-value"
11
      rename: "destination-header"
12
  # Remove the "x-legacy-account-id" header
13
  - remove:
14
      named: "x-legacy-account-id"
15
  # Remove matching headers
16
  - remove:
17
      matching: ^x-deprecated-.*
18
  # Insert the 'my-company' header
19
  - insert:
20
      name: "my-company"
21
      value: "acme"
22
  # Subgraph-specific header rules
23
  subgraphs:
24
    products:
25
      # Calls to the products subgraph have the "router-subgraph-name" header set to `products`.
26
      - insert:
27
          name: "router-subgraph-name"
28
          value: "products"
29
    accounts:
30
      # Calls to the accounts subgraph have the "router-subgraph-name" header set to `accounts`.
31
      - insert:
32
          name: "router-subgraph-name"
33
          value: "accounts"

Edit on GitHub

Logging

Traffic shaping