API Reference: Subscription callback plugin

This document covers the usage of the subscription callback plugin for use in Apollo Federation with Apollo Router. For more information about the protocol itself, see the subscription callback protocol.

Using the plugin

This article documents the options for the ApolloServerPluginSubscriptionCallback plugin, which you can import from @apollo/server/plugin/subscriptionCallback.

This plugin enables your GraphQL server to respond to subscription operations using the subscription callback protocol. Apollo Router uses this protocol to execute subscription operations and receive updates at a URL specified by the router.

This feature can only be enabled by providing an ApolloServerPluginSubscriptionCallback instance to your ApolloServer constructor:

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginSubscriptionCallback } from '@apollo/server/plugin/subscriptionCallback';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [ApolloServerPluginSubscriptionCallback()],
8
});

1
import { ApolloServer } from '@apollo/server';
2
import { ApolloServerPluginSubscriptionCallback } from '@apollo/server/plugin/subscriptionCallback';
3

4
const server = new ApolloServer({
5
  typeDefs,
6
  resolvers,
7
  plugins: [ApolloServerPluginSubscriptionCallback()],
8
});

Caveats

The subscription plugin implementation inherently bypasses Apollo Server's request lifecycle. This means that certain plugin hooks (notably executionDidStart and willResolveField) will not be called when handling callback subscription requests or when sending subscription events. There is currently no metrics or tracing support for callback subscriptions.

Options

1
{
2
  retries: 5,
3
  minTimeout: 100,
4
  maxTimeout: 1000,
5
}

1
new ApolloServer({
2
  plugins: [
3
    ApolloServerPluginSubscriptionCallback({
4
      retry: {
5
        retries: 3,
6
        minTimeout: 1000,
7
        maxTimeout: 5000,
8
        randomize: true,
9
      },
10
    }),
11
  ],
12
  // ...
13
})