Docs
Launch GraphOS Studio

Implementing a gateway with Apollo Server

Using a Node.js gateway as your graph router


After you set up at least one federation-ready subgraph, you can configure a graph router (also known as a gateway) to sit in front of your .

Graph router
Users
subgraph
Products
subgraph
Reviews
subgraph
Web app
iOS app

📣 In the majority of cases, we recommend using the Apollo Router as your graph router. It's faster to configure, it's more performant (especially with high request loads), and it rarely requires writing custom code.

In certain cases, you might need to use as your if your use a custom authentication method that is currently difficult to configure with the .

Regardless of which library you start with, you can swap to the other without making any changes to other parts of your .

Node.js gateway setup

This section walks through setting up a basic using and the @apollo/gateway library. It currently requires Node.js version 14 or 16.

Create a new Node.js project with npm init, then install the necessary packages:

npm install @apollo/gateway @apollo/server graphql

The @apollo/gateway package includes the ApolloGateway class. To configure to act as a , you pass an instance of ApolloGateway to the ApolloServer constructor, like so:

index.ts
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { ApolloGateway } from '@apollo/gateway';
import { readFileSync } from 'fs';
const supergraphSdl = readFileSync('./supergraph.graphql').toString();
// Initialize an ApolloGateway instance and pass it
// the supergraph schema as a string
const gateway = new ApolloGateway({
supergraphSdl,
});
// Pass the ApolloGateway to the ApolloServer constructor
const server = new ApolloServer({
gateway,
});
// Note the top-level `await`!
const { url } = await startStandaloneServer(server);
console.log(`🚀 Server ready at ${url}`);
index.js
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { ApolloGateway } from '@apollo/gateway';
import { readFileSync } from 'fs';
const supergraphSdl = readFileSync('./supergraph.graphql').toString();
// Initialize an ApolloGateway instance and pass it
// the supergraph schema as a string
const gateway = new ApolloGateway({
supergraphSdl,
});
// Pass the ApolloGateway to the ApolloServer constructor
const server = new ApolloServer({
gateway,
});
// Note the top-level `await`!
const { url } = await startStandaloneServer(server);
console.log(`🚀 Server ready at ${url}`);

Composing the supergraph schema

In the above example, we provide the supergraphSdl option to the ApolloGateway constructor. This is the string representation of our supergraph schema, which is composed from all of our .

To learn how to compose your , see Supported methods.

In production, we strongly recommend running the gateway in a managed mode with Apollo Studio, which enables your gateway to update its configuration without a restart. For details, see Setting up managed federation.

On startup, the gateway processes your supergraphSdl, which includes routing information for your . It then begins accepting incoming requests and creates for them that execute across one or more subgraphs.

Updating the supergraph schema

In the above example, we provide a static to the gateway. This approach requires the gateway to restart in order to update the supergraph schema. This is undesirable for many applications, so we also provide the ability to update the supergraph schema dynamically.

index.ts
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { ApolloGateway } from '@apollo/gateway';
import { readFile } from 'fs/promises';
let supergraphUpdate;
const gateway = new ApolloGateway({
async supergraphSdl({ update }) {
// `update` is a function that we'll save for later use
supergraphUpdate = update;
return {
supergraphSdl: await readFile('./supergraph.graphql', 'utf-8'),
};
},
});
// Pass the ApolloGateway to the ApolloServer constructor
const server = new ApolloServer({
gateway,
});
const { url } = await startStandaloneServer(server);
console.log(`🚀 Server ready at ${url}`);
index.js
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { ApolloGateway } from '@apollo/gateway';
import { readFile } from 'fs/promises';
let supergraphUpdate;
const gateway = new ApolloGateway({
async supergraphSdl({ update }) {
// `update` is a function that we'll save for later use
supergraphUpdate = update;
return {
supergraphSdl: await readFile('./supergraph.graphql', 'utf-8'),
};
},
});
// Pass the ApolloGateway to the ApolloServer constructor
const server = new ApolloServer({
gateway,
});
const { url } = await startStandaloneServer(server);
console.log(`🚀 Server ready at ${url}`);

There are a few things happening here. Let's take a look at each of them individually.

Note that supergraphSdl is now an async function. This function is called exactly once, when ApolloServer initializes the gateway. It has the following responsibilities:

  • It receives the update function, which we use to update the .
  • It returns the initial , which the gateway uses at startup.

With the update function, we can now programmatically update the . Polling, webhooks, and file watchers are all examples of ways we can go about doing this.

The code below demonstrates a more complete example using a file watcher. In this example, assume that we're updating the supergraphSdl.graphql file with the .

index.ts
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { ApolloGateway } from '@apollo/gateway';
import { watch } from 'fs';
import { readFile } from 'fs/promises';
const server = new ApolloServer({
gateway: new ApolloGateway({
async supergraphSdl({ update, healthCheck }) {
// create a file watcher
const watcher = watch('./supergraph.graphql');
// subscribe to file changes
watcher.on('change', async () => {
// update the supergraph schema
try {
const updatedSupergraph = await readFile('./supergraph.graphql', 'utf-8');
// optional health check update to ensure our services are responsive
await healthCheck(updatedSupergraph);
// update the supergraph schema
update(updatedSupergraph);
} catch (e) {
// handle errors that occur during health check or while updating the supergraph schema
console.error(e);
}
});
return {
supergraphSdl: await readFile('./supergraph.graphql', 'utf-8'),
// cleanup is called when the gateway is stopped
async cleanup() {
watcher.close();
},
};
},
}),
});
const { url } = await startStandaloneServer(server);
console.log(`🚀 Server ready at ${url}`);
index.js
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { ApolloGateway } from '@apollo/gateway';
import { watch } from 'fs';
import { readFile } from 'fs/promises';
const server = new ApolloServer({
gateway: new ApolloGateway({
async supergraphSdl({ update, healthCheck }) {
// create a file watcher
const watcher = watch('./supergraph.graphql');
// subscribe to file changes
watcher.on('change', async () => {
// update the supergraph schema
try {
const updatedSupergraph = await readFile('./supergraph.graphql', 'utf-8');
// optional health check update to ensure our services are responsive
await healthCheck(updatedSupergraph);
// update the supergraph schema
update(updatedSupergraph);
} catch (e) {
// handle errors that occur during health check or while updating the supergraph schema
console.error(e);
}
});
return {
supergraphSdl: await readFile('./supergraph.graphql', 'utf-8'),
// cleanup is called when the gateway is stopped
async cleanup() {
watcher.close();
},
};
},
}),
});
const { url } = await startStandaloneServer(server);
console.log(`🚀 Server ready at ${url}`);

This example is a bit more complete. Let's take a look at what we've added.

In the supergraphSdl callback, we also receive a healthCheck function. This enables us to run a health check against each of the services in our future . This is useful for ensuring that our services are responsive and that we don't perform an update when it's unsafe.

We've also wrapped our call to update and healthCheck in a try block. If an error occurs during either of these, we want to handle this gracefully. In this example, we continue running the existing and log an error.

Finally, we return a cleanup function. This is a callback that's called when the gateway is stopped. This enables us to cleanly shut down any ongoing processes (such as file watching or polling) when the gateway is shut down via a call to ApolloServer.stop. The gateway expects cleanup to return a Promise and awaits it before shutting down.

Advanced usage

In a more complex application, you might want to create a class that handles the update and healthCheck functions, along with any additional state. In this case, you can instead provide an object (or class) with an initialize function. This function is called just like the supergraphSdl function discussed above. For an example of this, see the IntrospectAndCompose source code.

Composing subgraphs with IntrospectAndCompose

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

Instead of providing a composed to the gateway, you can instruct the gateway to fetch all of your and perform itself. To do so, provide an instance of the IntrospectAndCompose class with a subgraphs array, like so:

index.ts
const { ApolloGateway, IntrospectAndCompose } = require('@apollo/gateway');
const gateway = new ApolloGateway({
supergraphSdl: new IntrospectAndCompose({
subgraphs: [
{ name: 'accounts', url: 'http://localhost:4001' },
{ name: 'products', url: 'http://localhost:4002' },
// ...additional subgraphs...
],
}),
});
index.js
const { ApolloGateway, IntrospectAndCompose } = require('@apollo/gateway');
const gateway = new ApolloGateway({
supergraphSdl: new IntrospectAndCompose({
subgraphs: [
{ name: 'accounts', url: 'http://localhost:4001' },
{ name: 'products', url: 'http://localhost:4002' },
// ...additional subgraphs...
],
}),
});

Each item in the subgraphs array is an object that specifies the name and url of one of your . You can specify any string value for name, which is used primarily for output, error messages, and logging.

On startup, the gateway fetches each 's schema from its url and composes those schemas into a . It then begins accepting incoming requests and creates for them that execute across one or more .

Additional configuration options can be found in the IntrospectAndCompose API documentation.

However, IntrospectAndCompose has important limitations.

Limitations of IntrospectAndCompose

The IntrospectAndCompose option can sometimes be helpful for local development, but it's strongly discouraged for any other environment. Here are some reasons why:

  • Composition might fail. With IntrospectAndCompose, your gateway performs dynamically on startup, which requires network communication with each . If composition fails, your gateway throws errors and experiences unplanned downtime.
    • With the static or dynamic supergraphSdl configuration, you instead provide a that has already been composed successfully. This prevents errors and enables faster startup.
  • Gateway instances might differ. If you deploy multiple instances of your gateway while deploying updates to your , your gateway instances might fetch different schemas from the same . This can result in sporadic failures or inconsistent between instances.
    • When you deploy multiple instances with supergraphSdl, you provide the exact same static artifact to each instance, enabling more predictable behavior.

Updating the gateway

Before updating your gateway's version, check the changelog for potential breaking changes.

We strongly recommend updating your gateway in local and test environments before deploying updates to staging or production.

You can confirm the currently installed version of the @apollo/gateway library with the npm list command:

npm list @apollo/gateway

To update the library, use the npm update command:

npm update @apollo/gateway

This updates the library to the most recent version allowed by your package.json file. Learn more about dependency constraints.

To update to a particular version (including a version that exceeds your dependency constraints), use npm install instead:

npm install @apollo/gateway@2.0.0

Customizing requests and responses

The gateway can modify the details of an incoming request before executing it across your . For example, your subgraphs might all use the same authorization token to associate an incoming request with a particular user. The gateway can add that token to each it sends to your subgraphs.

Similarly, the gateway can modify the details of its response to a client, based on the result returned by each .

Customizing requests

In the following example, each incoming request to the gateway includes an Authorization header. The gateway sets the shared contextValue for an by pulling the value of that header and using it to fetch the associated user's ID.

After adding the userId to the shared contextValue object, the gateway can then add that value to a header that it includes in its requests to each .

The of the object passed to your context function might differ if you're using a different Apollo Server integration.

The buildService function enables us to customize the requests that are sent to our . In this example, we return a custom RemoteGraphQLDataSource. This datasource enables us to modify the outgoing request with information from 's contextValue before it's sent. Here, we add the user-id header to pass an authenticated user ID to downstream services.

Customizing responses

Let's say that whenever a returns an result to the gateway, it includes a Server-Id header in the response. The value of the header uniquely identifies the in our graph.

When the gateway then responds to a client, we want its Server-Id header to include the identifier for every that contributed to the response. In this case, we can tell the gateway to aggregate the various server IDs into a single, comma-separated list.

The flow for processing a single from a client application then looks like this:

SubgraphsGatewayClient appSubgraphsGatewayClient apploop[For each operation in the query plan]Sends GraphQL operationGenerates query plan for operationSends the operation to the applicable subgraphResponds with result and Server-Id headerAdds the returned Server-Id to the shared contextAdds all Server-Ids in the shared context to the response headerSends operation response

To implement this flow, we can use the didReceiveResponse callback of the RemoteGraphQLDataSource class to inspect each 's result as it comes in. We can add the Server-Id to the shared context in this callback, then pull the full list from the context when sending the final response to the client.

In this example, multiple calls to didReceiveResponse are pushing a value onto the shared contextValue.serverIds array. The order of these calls cannot be guaranteed. If you write logic that modifies the shared contextValue object, make sure that modifications are not destructive, and that the order of modifications doesn't matter.

To learn more about buildService and RemoteGraphQLDataSource, see the API docs.

Custom directive support

The @apollo/gateway library supports the use of custom directives in your . This support differs depending on whether a given is a type system directive or an executable directive.

Type system directives

are directives that are applied to one of these locations. These are not used within , but rather are applied to locations within the schema itself.

The @deprecated below is an example of a directive:

directive @deprecated(
reason: String = "No longer supported"
) on FIELD_DEFINITION | ENUM_VALUE
type ExampleType {
newField: String
oldField: String @deprecated(reason: "Use `newField`.")
}

The gateway strips all definitions and uses of from your 's API schema. This has no effect on your , which retain this information.

Effectively, the gateway supports by ignoring them, making them the responsibility of the that define them.

Executable directives

Executable are directives that are applied to one of these locations. These are defined in your schema, but they're used in that are sent by clients.

Here's an example of an executable definition:

# Uppercase this field's value (assuming it's a string)
directive @uppercase on FIELD

And here's an example of a that uses that :

query GetUppercaseUsernames {
users {
name @uppercase
}
}

It's strongly recommended that all of your use the exact same logic for a given executable . Otherwise, might produce inconsistent or confusing results for clients.

Previous
@apollo/subgraph reference
Next
@apollo/gateway reference
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company