API Reference: ApolloServer

This article documents the ApolloServer class from the @apollo/server package. You can use the ApolloServer class to create an instance of Apollo Server that you can then pass to a web framework integration function (e.g., startStandaloneServer or expressMiddleware).

Check out our Getting Started guide for an example of setting up Apollo Server!

constructor

Returns an initialized ApolloServer instance.

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

Example

1import { ApolloServer } from '@apollo/server';
2
3const server = new ApolloServer({
4  typeDefs,
5  resolvers,
6});

Options

1import { InMemoryLRUCache } from '@apollo/utils.keyvaluecache';
2import type { DocumentNode } from 'graphql';
3
4new ApolloServer({
5  documentStore: new InMemoryLRUCache<DocumentNode>({
6    maxSize: Math.pow(2, 20) * approximateDocumentStoreMiB,
7    sizeCalculation: InMemoryLRUCache.sizeCalculation,
8  }),
9  // ...
10});

start

The async start method instructs Apollo Server to prepare to handle incoming operations.

Call start only if you are using a framework integration for a non-serverless environment (e.g., expressMiddleware).

• If you're using a serverless framework integration (such as Lambda), you shouldn't call this method before passing your server into the integration function. Your serverless integration function will take care of starting your server for you.

• If you're using startStandaloneServer you do not need to start your server before passing it directly to startStandaloneServer.

Always call await server.start() before passing your server into your integration function and starting to accept requests:

1const server = new ApolloServer<MyContext>({
2  typeDefs,
3  resolvers,
4});
5await server.start();
6
7app.use(
8  '/graphql',
9  cors<cors.CorsRequest>(),
10  express.json(),
11  expressMiddleware(server),
12);

This allows you to react to Apollo Server startup failures by crashing your process instead of starting to serve traffic.

If you are testing your server using executeOperation (i.e., you're not actually starting an HTTP server), you don't need to call start() because executeOperation will do that for you.

Triggered actions

The start method triggers the following actions:

1. If your server is a federated gateway, it attempts to fetch its schema. If the fetch fails, start throws an error.

2. Your server calls all of the serverWillStart handlers of your installed plugins. If any of these handlers throw an error, start throws an error.

startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests

Serverless integrations handle starting an Apollo Server instance in the background by calling the startInBackgroundHandlingStartupErrorsByLoggingAndFailingAllRequests method. This method is synchronous and doesn't need to be awaited. This means any errors that occur happen in the background, so you can't immediately handle them. See Building integrations for more details.

This method triggers the same actions as the start() method.

addPlugin

You can use the addPlugin method to add plugins before your server is started. This is helpful when you want to add a plugin that accepts your initialized ApolloServer instance itself, like so:

1const server = new ApolloServer({
2  typeDefs,
3  plugins: [makeFirstPlugin()],
4});
5
6server.addPlugin(makeSecondPlugin(server));

assertStarted

Framework integrations should call server.assertStarted() to ensure a server has started before accepting requests. See Building integrations for more details.

stop

ApolloServer.stop() is an async method that tells all of Apollo Server's background tasks to complete. Specifically, it:

• Calls and awaits all drainServer plugin handlers. These should generally:

  • Stop listening for new connections

  • Close idle connections (i.e., connections with no current HTTP request)

  • Close active connections whenever they become idle

  • Wait for all connections to be closed

  • After a grace period, if any connections remain active, forcefully close them. If you're using startStandaloneServer, this happens by default. Otherwise, you can use the drain HTTP server plugin to drain your HTTP server.

• Transitions the server to a state where it will not start executing more GraphQL operations.

• Calls and awaits all serverWillStop plugin handlers (including the usage reporting plugin's handler, which sends a final usage report to Apollo Studio).

• If your server is a federated gateway, stop also stops gateway-specific background activities, such as polling for updated service configuration.

This method takes no arguments. You should only call it after start() returns successfully (or after you've called startStandaloneServer with your ApolloServer instance).

In some circumstances, Apollo Server calls stop automatically when the process receives a SIGINT or SIGTERM signal. See the stopOnTerminationSignals constructor option for details.

executeOperation

The async executeOperation method is used primarily for testing GraphQL operations through Apollo Server's request pipeline without sending an HTTP request.

1const response = await server.executeOperation({
2  query: 'query SayHelloWorld($name: String) { hello(name: $name) }',
3  variables: { name: 'world' },
4});

The executeOperation method takes two arguments:

• The first argument is an object describing the GraphQL operation to be executed.

  • Supported fields are listed in the table below.

• The second argument is the optional options object. This object includes the operation's optional contextValue. This argument is only optional if your server doesn't expect a context value (i.e., your server uses the default context because you didn't explicitly provide another one).

1const response = await server.executeOperation({
2  query: 'query SayHelloWorld($name: String) { hello(name: $name) }',
3  variables: { name: 'world' },
4}, {
5  contextValue: { userId: 'test' },
6});

The response object returned from executeOperation is a GraphQLResponse, which has body and http fields.

Apollo Server 4 supports incremental delivery directives such as @defer and @stream (when combined with an appropriate version of graphql-js), and so the structure of response.body can represent either a single result or multiple results. response.body.kind is either 'single' or 'incremental'. If it is 'single', then incremental delivery has not been used, and response.body.singleResult is an object with data, errors, and extensions fields. If it is 'incremental', then response.body.initialResult is the initial result of the operation, and response.body.subsequentResults is an async iterator that will yield subsequent results. (The precise structure of initialResult and subsequentResults is defined by graphql-js and may change between the current pre-release of graphql-js v17 and its final release; if you write code that processes these values before graphql-js v17 has been released you may have to adapt it when the API is finalized.)

The http field contains an optional numeric status code and a headers map specifying any HTTP status code and headers that should be set.

Below are the available fields for the first argument of executeOperation:

Fields

executeHTTPGraphQLRequest

The executeHTTPGraphQLRequest method is the main entry point for web framework integrations. You can pass a HTTPGraphQLRequest object to the executeHTTPGraphQLRequest method to execute a GraphQL request:

1const result = await server.executeHTTPGraphQLRequest({
2  httpGraphQLRequest: OurHttpGraphQLRequest,
3  context: async () => ({
4    // token: ...,
5  }),
6});

For details and examples, see Building Integrations.

cache

A public readonly field on ApolloServer that enables you to access your server's cache.

logger

A public readonly field on ApolloServer that enables you to access your server's logger.