/

API Reference: @apollo/gateway

Apollo Gateway API reference

ApolloGateway

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

constructor(options): ApolloGateway

Parameters

  • options: Object

    An object that contains configuration options for the gateway.

    Supported options include:

    • serviceList: ServiceDefinition[]

      Do not provide this option if you are using managed configuration. If you are not using managed configuration, this option is required.

      An array representing the implementing services that the gateway will use to resolve incoming GraphQL operations. Each object in the array specifies the name and url of an 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 Graph Manager.

      const gateway = new ApolloGateway({
  ...
  serviceList: [    { name: 'products', url: 'https://products-service.dev/graphql' },    { name: 'reviews', url: 'https://reviews-service.dev/graphql' }  ]});

    • buildService: (service: ServiceDefinition) => GraphQLDataSource

      Define this function to customize your gateway's data transport to some or all of your data graph's implementing services. This customization can include using a protocol besides the default of HTTP.

      If you provide this function, ApolloGateway calls it for every implementing service in your data graph. 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({
  ...
  buildService({ name, url }) {    return new AuthenticatedDataSource({ url });  },});

    • introspectionHeaders: { [key: string]: string }

      An object containing HTTP headers that the gateway will include only when obtaining schema definitions from each of your implementing services.

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

      const gateway = new ApolloGateway({
  ...
  introspectionHeaders: {    Authorization: 'my-header'  }});

    • debug: Boolean

      If true, the gateway logs startup messages, along with the query plan for each incoming request. The default value is false.

Returns

An ApolloGateway instance, which you then pass as the gateway configuration option to the ApolloServer constructor, like so:

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

RemoteGraphQLDataSource

A RemoteGraphQLDataSource object represents a connection between your federated gateway and one of your implementing services.

You can customize this connection by defining a subclass of this class and overriding its willSendRequest and/or didReceiveResponse methods:

  • The willSendRequest method lets you modify your gateway's requests to the implementing service before they're sent.
  • The didReceiveResponse method lets you modify the implementing service's responses before the gateway passes them along to the requesting client.

These methods are described in detail below.

constructor(options): RemoteGraphQLDataSource

Parameters

  • options: Object

    An object that contains configuration options for the data source.

    Supported options include:

    • url: string (required)

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

    willSendRequest: (requestContext: {request: GraphQLRequest, context: Record<string, any>}) => Promise<void>

    Override this method to customize the structure of each fetch that's sent to the implementing service. The method accepts an object that contains both the original incoming request and the current context.

    The example below demonstrates using the willSendRequest method to add 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);  }});

    didReceiveResponse: (response: Response, request: Request, context: TContext) => Promise<TResult>

    Override this method to customize the gateway's behavior after completing a fetch to the implementing service. The method takes the original request, the implementing service's response, and the current context as parameters, allowing you to modify any combination of the context and the final result of the fetch.

    This method must return an object that matches the structure of a GraphQLExecutionResult (i.e., it should include data, errors, and/or extensions fields).

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