GraphQL Summit is back for three days of insights, hands-on learning, and fun to celebrate the GraphQL community. Join us in San Diego Oct 3-5.
Docs
Try Apollo Studio

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
# ...other configuration...
headers:
all: # Header rules for all subgraphs
request:
- propagate:
matching: ^upstream-header-.*
- remove:
named: "x-legacy-account-id"
subgraphs:
products: # Header rules for just the products subgraph
request:
- insert:
name: "router-subgraph-name"
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:

- propagate:
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
- propagate:
named: "x-user-id"
default: "abc123"
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.

# Do not send this subgraph the "Cookie" header.
- remove:
named: "Cookie"
- remove:
# Remove headers that include the legacy 'x-' prefix.
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.

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

Rule ordering

Header rules are applied in the same order they're declared, and later rules can override the effects of earlier rules. Consider this example:

bad_configuration.yaml
headers:
all:
request:
- remove:
named: "test"
- propagate:
matching: .*

In this example, first any header named test is removed from the list of headers to propagate. However, the list of headers to propagate is currently empty! Next, the propagate rule adds all headers to the propagation list, including test.

To correctly remove a header from the propagation list, make sure to define your remove rule after any propagate rules:

good_configuration.yaml
headers:
all:
request:
- propagate:
matching: .*
- remove:
named: "test"

With this ordering, first all headers are added to the propagation list, then the test header is removed.

Example

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

router.yaml
headers:
# Header rules for all subgraphs
all:
request:
# Propagate matching headers
- propagate:
matching: ^upstream-header-.*
# Propagate matching headers
- propagate:
named: "some-header"
default: "default-value"
rename: "destination-header"
# Remove the "x-legacy-account-id" header
- remove:
named: "x-legacy-account-id"
# Remove matching headers
- remove:
matching: ^x-deprecated-.*
# Insert the 'my-company' header
- insert:
name: "my-company"
value: "acme"
# Subgraph-specific header rules
subgraphs:
products:
request:
# Calls to the products subgraph have the "router-subgraph-name" header set to `products`.
- insert:
name: "router-subgraph-name"
value: "products"
accounts:
request:
# Calls to the accounts subgraph have the "router-subgraph-name" header set to `accounts`.
- insert:
name: "router-subgraph-name"
value: "accounts"
Edit on GitHub
Previous
Logging
Next
Traffic shaping