API Reference: @apollo/gateway

This API reference documents the exports from the @apollo/gateway package. This package enables you to use Apollo Server as a gateway for a federated supergraph. For more information, see Implementing a gateway with Apollo Server.

We recommend that all supergraphs use the GraphOS Router instead of this Node.js-based gateway. See Choosing a router library.

class ApolloGateway

The core class of Apollo Server's federated gateway implementation. For an example of using ApolloGateway, see Implementing a gateway with Apollo Server.

Methods

constructor

Returns an initialized ApolloGateway instance, which you can then pass as the gateway configuration option to the ApolloServer constructor, like so:

1const server = new ApolloServer({
2  gateway: new ApolloGateway({
3    serviceList: [
4      // ...
5    ],
6  }),
7});

Takes an options object as a parameter. Supported fields of this object are described below.

Examples

Providing a serviceList and headers to authorize introspection

1const gateway = new ApolloGateway({
2  serviceList: [
3    { name: 'products', url: 'https://products-service.dev/graphql' },
4    { name: 'reviews', url: 'https://reviews-service.dev/graphql' },
5  ],
6  introspectionHeaders: {
7    Authorization: 'Bearer abc123',
8  },
9});

Configuring the subgraph fetcher

If you provide a buildService function to the constructor of ApolloGateway, the function is called once for each of your graph's subgraphs. This function can return a RemoteGraphQLDataSource with a custom fetcher, which is then used for all communication with subgraphs:

1const gateway = new ApolloGateway({
2  buildService({ url, name }) {
3    return new (class extends RemoteGraphQLDataSource {
4      fetcher = require('make-fetch-happen').defaults({
5        onRetry() {
6          console.log('We will retry!');
7        },
8      });
9    })({
10      url,
11      name,
12    });
13  },
14});

Configuring the managed federation fetcher

This only configures the fetcher that your gateway uses to fetch managed federation configuration from Apollo.

See also Configuring the subgraph fetcher.

1const gateway = new ApolloGateway({
2  fetcher: require('make-fetch-happen').defaults({
3    onRetry() {
4      console.log('We will retry!');
5    },
6  }),
7});

Options

The buildService function

If you provide this function, the gateway calls it once for each subgraph. The function must return an object that implements the GraphQLDataSource interface, such as an instance of RemoteGraphQLDataSource or a subclass of it.

The example below demonstrates adding an x-user-id HTTP header to every request the gateway sends to a subgraph:

1class AuthenticatedDataSource extends RemoteGraphQLDataSource {
2  willSendRequest({ request, context }) {
3    request.http.headers.set('x-user-id', context.userId);
4  }
5}
6
7const gateway = new ApolloGateway({
8  // ...other options...
9  buildService({ name, url }) {
10    return new AuthenticatedDataSource({ url });
11  },
12});

Experimental options

These options are experimental. They might be removed or change at any time, even within a patch release.

serviceHealthCheck

When called, the gateway sends a small query ({ __typename }) to each subgraph to verify that they're all responsive. This function throws on failure and returns a Promise to be awaited.

Parameters

class RemoteGraphQLDataSource

Represents a connection between your federated gateway and one of your subgraphs.

You can customize this connection by extending this class and overriding its willSendRequest and/or didReceiveResponse methods:

• Override willSendRequest to modify your gateway's requests to the subgraph before they're sent.

• Override didReceiveResponse to modify the subgraph's responses before the gateway passes them along to the requesting client.

These methods are described in detail below.

Methods

constructor

Returns an initialized RemoteGraphQLDataSource instance:

1const productsDataSource = new RemoteGraphQLDataSource({
2  url: 'https://products-service.dev/graphql',
3});

Takes an options object as a parameter. Supported fields of this object are described below.

Options

willSendRequest

Override this method in a subclass to modify each outgoing fetch request before it's sent to the subgraph:

1// Adds an `x-user-id` header to each outgoing fetch request
2class AuthenticatedDataSource extends RemoteGraphQLDataSource {
3  willSendRequest({ request, context }) {
4    request.http.headers.set('x-user-id', context.userId);
5  }
6};

This method takes a requestContext object that contains both the original unmodified request and the current context object (i.e., the contextValue object).

didReceiveResponse

Override this method in a subclass to customize the gateway's behavior after it completes a fetch to the subgraph, but before it sends a response to the requesting client:

1class CookieDataSource extends RemoteGraphQLDataSource {
2  didReceiveResponse({ response, request, context }) {
3    const cookie = request.http.headers.get('Cookie');
4    if (cookie) {
5      context.responseCookies.push(cookie);
6    }
7
8    // Return the response, even when unchanged.
9    return response;
10  }
11}

This method takes a requestContext object that contains:

• The subgraph's response

• The gateway's request to the subgraph

• The current operation's context (i.e., the contextValue object)

This enables you to modify any combination of the operation's contextValue and the response of the fetch.

The http property of the request and response objects contains additional HTTP-specific properties, such as headers.

This method must return an object that matches the structure of a GraphQLResponse. If no modifications are necessary, return the original response.

didEncounterError

Override this method in a subclass to customize the gateway's behavior after it encounters an error while communicating with the subgraph or while parsing its response (e.g., if the response is not well-formed JSON).

If you don't override this method, the default implementation throws the error, like so:

1class MyDataSource extends RemoteGraphQLDataSource {
2  didEncounterError(error, fetchRequest, fetchResponse, context) {
3    throw error;
4  }
5}

Note that if you don't throw error (or a different Error) in this method, error is thrown immediately after this method returns.

This method takes the following positional parameters:

class IntrospectAndCompose

⚠️ We strongly recommend against using IntrospectAndCompose in production. For details, see Limitations of IntrospectAndCompose.

IntrospectAndCompose is a development tool for fetching and composing subgraph SDL into a supergraph for your gateway. Given a list of subgraphs and their URLs, IntrospectAndCompose will issue queries for their SDL, compose them into a supergraph, and provide that supergraph to the gateway. It can also be configured to update via polling and perform subgraph health checks to ensure that supergraphs are updated safely. IntrospectAndCompose implements the SupergraphManager interface and is passed in to ApolloGateway's supergraphSdl constructor option.

IntrospectAndCompose is the drop-in replacement for serviceList.

Methods

constructor

Returns an initialized IntrospectAndCompose instance, which you can then pass to the supergraphSdl configuration option of the ApolloGateway constructor, like so:

1const server = new ApolloServer({
2  gateway: new ApolloGateway({
3    supergraphSdl: new IntrospectAndCompose({
4      subgraphs: [
5        // ...
6      ],
7    }),
8  }),
9});

Takes an options object as a parameter. Supported properties of this object are described below.

Examples

Providing a subgraphs list and headers to authorize introspection

1const gateway = new ApolloGateway({
2  supergraphSdl: new IntrospectAndCompose({
3    subgraphs: [
4      { name: 'products', url: 'https://products-service.dev/graphql' },
5      { name: 'reviews', url: 'https://reviews-service.dev/graphql' },
6    ],
7    introspectionHeaders: {
8      Authorization: 'Bearer abc123',
9    },
10  }),
11});

Configuring the subgraph fetcher

IntrospectAndCompose uses the data sources constructed by ApolloGateway. To customize the gateway's data sources, you can provide a buildService function to the ApolloGateway constructor. In the example below, IntrospectAndCompose makes authenticated requests to the subgraphs via the AuthenticatedDataSources that we construct in the gateway's buildService function.

1const gateway = new ApolloGateway({
2  buildService({ name, url }) {
3    return new AuthenticatedDataSource({ url });
4  },
5  supergraphSdl: new IntrospectAndCompose({
6    subgraphs: [
7      { name: 'products', url: 'https://products-service.dev/graphql' },
8      { name: 'reviews', url: 'https://reviews-service.dev/graphql' },
9    ],
10  }),
11});

Options