/
Launch Apollo Studio

API Reference: @apollo/gateway

Apollo Gateway API reference


This API reference documents the exports from the @apollo/gateway package.

class ApolloGateway

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

Methods

constructor

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

const server = new ApolloServer({
  gateway: new ApolloGateway({    serviceList: [      // ...    ]  }),});

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

Examples
Providing a serviceList and headers to authorize introspection
const gateway = new ApolloGateway({
  serviceList: [
    { name: 'products', url: 'https://products-service.dev/graphql' },
    { name: 'reviews', url: 'https://reviews-service.dev/graphql' }
  ],
  introspectionHeaders: {
    Authorization: 'Bearer abc123'
  }
});
Configuring the fetcher
const gateway = new ApolloGateway({
  fetcher: require('make-fetch-happen').defaults({
    onRetry() {
      console.log('we will retry!')
    },
  }),
});
Options
Name /
Type
Description
serviceList

Array<ServiceDefinition>

An array of objects that each specify the name and url of one implementing service in your federated graph.

You can specify any string value for the name field, which is used for identifying the service in log output and error messages, and for reporting metrics to Apollo Studio.

If you are using managed federation, do not provide this field.

If you aren't using managed federation, this field is required.

introspectionHeaders

Object

An object containing the names and values of HTTP headers that the gateway includes only when making introspection requests to your implementing services.

If you are using managed federation, do not provide this field.

If you define a buildService function, specify these headers in that function instead of providing this option. This ensures that your buildService function doesn't inadvertently overwrite the values of any headers you provide here.

debug

Boolean

If true, enables development mode helpers and logs messages of all severity levels (debug through error). If false, only warn- and error-level messages are logged.

The default value is false.

logger

Logger

An object to use for logging in place of console. If provided, this object must implement all methods of the Logger interface.

If you provide this value, the gateway automatically logs all messages of all severity levels (debug through error), regardless of whether the debug option is set to true. It is the responsibility of the logger to determine how to handle logged messages of each level.

This logger is automatically added to the GraphQLRequestContext object that's passed to all Apollo Server plugin functions.

fetcher

typeof fetch

Specifies which Fetch API implementation to use when communicating with implementing services.

By default, the gateway uses the default configuration of make-fetch-happen. You can specify another valid implementation (such as node-fetch) by setting this field's value to require('node-fetch').

As shown in the example above, you can also provide make-fetch-happen to this option if you want to override the library's default configuration.

serviceHealthCheck

Boolean

If true, the gateway sends a small query ({ __typename }) to all implementing services on gateway startup. It also does the same on each live schema update if you're using managed federation.

On startup, the gateway throws an error if any of these requests fail.

On schema update, the gateway does not roll over to the new schema or service configuration if any of these requests fail. The gateway retries the requests at each polling interval until they succeed.

The default value is false.

buildService

Function

Define this function to customize your gateway's data transport to some or all of your implementing services. This customization can include using a protocol besides HTTP. For details, see The buildService function.

The buildService function

If you provide this function, the gateway calls it once for each implementing service. 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 an implementing service:

class AuthenticatedDataSource extends RemoteGraphQLDataSource {
  willSendRequest({ request, context }) {
    request.http.headers.set('x-user-id', context.userId);
  }
}

const gateway = new ApolloGateway({
  // ...other options...
  buildService({ name, url }) {    return new AuthenticatedDataSource({ url });  },});
Experimental options

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

Name /
Type
Description
experimental_approximateQueryPlanStoreMiB

number

Sets the approximate size (in MiB) of the gateway's query plan store. This cache is used to save query plans for reuse on subsequent queries that resolve to a previously observed queryHash (the SHA-256 of the incoming operation).

The default value is 30, which is usually sufficient unless the server processes a large number of unique operations.

serviceHealthCheck

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

Parameters
Name /
Type
Description
serviceMap

Object (DataSourceMap)

If provided, the gateway sends health check requests to only the data sources included in the map.

By default, the gateway uses this.serviceMap (i.e., it sends health check requests to all known implementing services).

class RemoteGraphQLDataSource

Represents a connection between your federated gateway and one of your implementing services.

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 implementing service before they're sent.
  • Override didReceiveResponse to modify the implementing service'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:

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

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

Options
Name /
Type
Description
url

String

Required. The implementing service's URL for sending fetch requests via HTTP.

apq

Boolean

If true, the gateway attempts to use automated persisted queries (APQ) when sending queries to this implementing service. APQ can dramatically reduce the size of most requests sent over the network, especially for more complex queries.

The implementing service must also enable support for APQ for the gateway to use this feature (Apollo Server enables APQ by default).

willSendRequest

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

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

This method takes a requestContext object that contains both the original unmodified request and the current context.

didReceiveResponse

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

class CookieDataSource extends RemoteGraphQLDataSource {
  didReceiveResponse({ response, request, context }) {
    const cookie = request.http.headers.get('Cookie');
    if (cookie) {
      context.responseCookies.push(cookie);
    }

    // Return the response, even when unchanged.
    return response;
  }
}

This method takes a requestContext object that contains:

  • The implementing service's response
  • The gateway's request to the implementing service
  • The current operation's context

This enables you to modify any combination of the operation's context 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.

Edit on GitHub