Apollo Link overview

The Apollo Link library helps you customize the flow of data between Apollo Client and your GraphQL server. You can define your client's network behavior as a chain of link objects that execute in a sequence:

Each link should represent either a self-contained modification to a GraphQL operation or a side effect (such as logging).

In the above diagram:

1. The first link might log the details of the operation for debugging purposes.

2. The second link might add an HTTP header to the outgoing operation request for authentication purposes.

3. The final link (called the terminating link) sends the operation to its destination (usually a GraphQL server over HTTP).

4. The server's response is passed back up each link in reverse order, enabling links to modify the response or take other actions before the data is cached.

Composing a link chain

A link chain consists of one or more link objects. Each link represents either a self-contained modification to a GraphQL operation or a side effect (such as logging). By composing these links into a chain, you can create an arbitrarily complex model for your client's data flow.

When you compose multiple links together, the result is a single link object that represents the entire chain. You provide the composed link to your Apollo Client instance using the link option:

1import { ApolloClient, InMemoryCache } from "@apollo/client";
2
3const client = new ApolloClient({
4  link: /* your composed link */,
5  cache: new InMemoryCache(),
6});

The terminating link

The last link in the link chain is called the terminating link. Instead of calling the forward function, it is responsible for sending the GraphQL operation to the destination that executes it (typically a GraphQL server) and returning a result. If a link chain consists of a single link, the single link is the terminating link.

HttpLink and BatchHttpLink are examples of terminating links.

Link composition

You compose multiple links together to form a link chain using two forms of link composition: additive and directional.

• Additive composition involves combining a set of links into a serially executed chain:

• Directional composition involves branching to one of two links, depending on the details of an operation:

Additive composition

Additive composition composes a link chain by executing links in serial order. You use the ApolloLink.from and ApolloLink.concat helpers to create a link chain using additive composition.

ApolloLink.from

The most common way to compose multiple links together is to use the static ApolloLink.from helper. Pass an array of link objects to ApolloLink.from to create a composed link that executes each link in serial order:

1import { HttpLink, ApolloLink } from "@apollo/client";
2import { RetryLink } from "@apollo/client/link/retry";
3import MyAuthLink from "../auth";
4
5const link = ApolloLink.from([
6  new RetryLink(),
7  new MyAuthLink(),
8  new HttpLink({ uri: "http://localhost:4000/graphql" }),
9]);

ApolloLink.concat

Each link object includes a concat instance method to combine two links into a single composed link. This is useful to combine multiple links together using a chain of function calls:

1import { ApolloLink, HttpLink } from "@apollo/client";
2import { RetryLink } from "@apollo/client/link/retry";
3import MyAuthLink from "../auth";
4
5const link = new RetryLink()
6  .concat(new MyAuthLink())
7  .concat(new HttpLink({ uri: "http://localhost:4000/graphql" }));

Directional composition

You might want your link chain's execution to branch, depending on the details of the operation being performed. You use the ApolloLink.split method to create a link that conditionally routes to different sub-chains.

The ApolloLink.split function takes three arguments:

The following example uses ApolloLink.split to create a link that routes to different HttpLink instances depending on the associated context's version:

1import { ApolloLink, HttpLink } from "@apollo/client";
2
3const link = ApolloLink.split(
4  (operation) => operation.getContext().version === 1,
5  new HttpLink({ uri: "http://localhost:4000/v1/graphql" }),
6  new HttpLink({ uri: "http://localhost:4000/v2/graphql" })
7);

1const link = previousLink.split(
2  (operation) => operation.getContext().version === 1,
3  new HttpLink({ uri: "http://localhost:4000/v1/graphql" }),
4  new HttpLink({ uri: "http://localhost:4000/v2/graphql" })
5);

Other uses for the split method include:

• Using different transport methods depending on the operation type (such as HTTP for queries and WebSocket for subscriptions)

• Customizing the number of allowed retry attempts depending on the operation type

• Customizing logic depending on whether a user is logged in

In the following example, all subscription operations are sent to GraphQLWsLink, with all other operations sent to HttpLink:

1import { ApolloLink, HttpLink } from "@apollo/client";
2import { GraphQLWsLink } from "@apollo/client/link/subscriptions";
3import { OperationTypeNode } from "graphql";
4import { createClient } from "graphql-ws";
5
6const link = ApolloLink.split(
7  ({ operationType }) => {
8    return operationType === OperationTypeNode.SUBSCRIPTION;
9  },
10  new GraphQLWsLink(createClient({ url: "ws://localhost:3000/subscriptions" })),
11  new HttpLink({ uri: "http://localhost:4000/graphql" })
12);

Creating a custom link

A link object is an instance of the ApolloLink class. Each link must define a request handler to handle the request.

The request handler

Every link must define a request handler. The request handler is a method responsible for performing some logic and executing the request, either by forwarding the operation to the next link in the chain, or sending the operation to the destination that executes it, such as a GraphQL server.

This request handler receives the following arguments:

• operation: The operation object that provides information about the currently executed GraphQL request passed through the link.

• forward: A function called to execute the next link in the chain.

Apollo Client executes a GraphQL operation by calling the request handler of the first link in the composed link chain. Each non-terminating link is then responsible for executing its logic and delegating execution down to the next link by calling the forward function. After the operation reaches the terminating link, the request handler sends the operation to the destination and reports the result back up through the chain.

Define a request handler using a callback function

The most common way to provide a request handler is by passing a callback function to the ApolloLink constructor:

1import { ApolloLink } from "@apollo/client";
2
3const link = new ApolloLink((operation, forward) => {
4  // Handle the request
5});

The callback function is called for each GraphQL operation sent through the link chain.

Define a request handler for an Apollo Link subclass

You define a request handler for a subclass of ApolloLink by overriding the request method. Subclassing is typically used to create stateful links.

1class MyCustomLink extends ApolloLink {
2  constructor() {
3    super();
4    // ...other setup logic
5  }
6
7  request(operation, forward) {
8    // Handle the request
9  }
10}

The request method is called for each GraphQL operation sent through the link chain.

The Operation object

The Operation object includes the following fields:

The forward function

After your custom link's request handler is finished performing its logic, return a call to the forward function and provide the operation as an argument. Calling the forward function executes the next link in the chain.

1const link = new ApolloLink((operation, forward) => {
2  // ...Handle the request
3
4  // Execute the next link in the chain
5  return forward(operation);
6});

The forward function returns an Observable provided by the RxJS library. Learn more about Observables in the RxJS documentation.

Handling a response

When your GraphQL server responds with an operation result, that result is passed back up through each link in your chain:

Each link can perform custom logic on the result using operators. These are special functions passed to an Observable's pipe function.

The following example uses the RxJS map operator to modify the result before returning it back up the chain:

1import { map } from "rxjs";
2
3const link = new ApolloLink((operation, forward) => {
4  return forward(operation).pipe(
5    map((result) => {
6      // ...modify result as desired here...
7      return result;
8    })
9  );
10});

This modification is seen by any previous link in the chain because the result travels back up the chain in reverse order.

Executing side-effects

Links commonly perform side-effects when receiving responses instead of modifying the result.

The following example uses the tap operator to estimate the round-trip time of an operation by defining a start time on the request context then logging the total time when the response is received.

1import { ApolloLink } from "@apollo/client";
2import { tap } from "rxjs";
3
4const roundTripLink = new ApolloLink((operation, forward) => {
5  // Called before operation is sent to server
6  operation.setContext({ start: new Date() });
7
8  return forward(operation).pipe(
9    tap((result) => {
10      // Called after server responds
11      const time = new Date() - operation.getContext().start;
12      console.log(
13        `Operation ${operation.operationName} took ${time} to complete`
14      );
15    })
16  );
17});

Link types

Stateless links

Most links perform the same logic for every operation they process and they don't need to know anything about operations that have been executed previously. These links are stateless.

Stateless links typically define request handlers by providing a callback function to the constructor of an ApolloLink object:

1import { ApolloLink } from "@apollo/client";
2import { tap } from "rxjs";
3
4const consoleLink = new ApolloLink((operation, forward) => {
5  console.log(`starting request for ${operation.operationName}`);
6  return forward(operation).pipe(
7    tap(() => {
8      console.log(`ending request for ${operation.operationName}`);
9    })
10  );
11});

Stateless links are great for building middleware. The following link adds an Authorization header to every outgoing request:

1import { ApolloLink } from "@apollo/client";
2
3const authLink = new ApolloLink((operation, forward) => {
4  operation.setContext(({ headers }) => ({
5    headers: {
6      authorization: Auth.userId(), // however you get your token
7      ...headers,
8    },
9  }));
10
11  return forward(operation);
12});

You can customize stateless links by wrapping them in a function:

1import { ApolloLink } from "@apollo/client";
2
3function reportErrors(errorCallback) {
4  return new ApolloLink((operation, forward) => {
5    return new Observable((observer) => {
6      const observable = forward(operation);
7      const subscription = observable.subscribe({
8        next(value) {
9          observer.next(value);
10        },
11        error(networkError) {
12          errorCallback({ networkError, operation });
13          observer.error(networkError);
14        },
15        complete() {
16          observer.complete();
17        },
18      });
19
20      return () => subscription.unsubscribe();
21    });
22  });
23}
24
25const link = reportErrors(console.error);

Extending ApolloLink

You can also create stateless links by subclassing the ApolloLink class and overriding the constructor and request handler.

Here's the same reportErrors link written as a subclass of ApolloLink:

1import { ApolloLink } from "@apollo/client";
2import { tap } from "rxjs";
3
4class ReportErrorLink extends ApolloLink {
5  constructor(errorCallback) {
6    super();
7    this.errorCallback = errorCallback;
8  }
9  request(operation, forward) {
10    return forward(operation).pipe(
11      tap({
12        // errors will be sent to the errorCallback
13        error: this.errorCallback,
14      })
15    );
16  }
17}
18
19const link = new ReportErrorLink(console.error);

Stateful links

Links that maintain state between operations are called stateful links. You create stateful links by defining subclasses of ApolloLink and overriding the constructor and request methods.

The following example maintains an operation counter using an instance variable. The counter is incremented for every request that passes through the link.

1import { ApolloLink } from "@apollo/client";
2
3class OperationCountLink extends ApolloLink {
4  constructor() {
5    super();
6    this.operationCount = 0;
7  }
8  request(operation, forward) {
9    this.operationCount += 1;
10    return forward(operation);
11  }
12}
13
14const link = new OperationCountLink();

Managing context

As an operation moves along the link chain, it maintains a context that each link can read and modify. This enables both links and request-based APIs (such as useQuery) to pass metadata along the chain that other links use in their execution logic. Context is not included in the terminating link's request to the GraphQL server or other destination.

Reading context

You get the current context object by calling operation.getContext() in a request handler.

1const link = new ApolloLink((operation, forward) => {
2  const context = operation.getContext();
3
4  // handle the request
5});

Modifying context

Modify context by calling operation.setContext(). You provide the updated context as an object directly to setContext.

1const timeStartLink = new ApolloLink((operation, forward) => {
2  operation.setContext({ start: new Date() });
3
4  return forward(operation);
5});

It is common to read existing context to make modifications to it before writing it back. As a shortcut, you can provide a callback function to operation.setContext(). The callback function provides the previous context as an argument and expects the function to return the new context.

1const counterLink = new ApolloLink((operation, forward) => {
2  operation.setContext((prevContext) => ({
3    count: prevContext.count + 1,
4  }));
5
6  return forward(operation);
7});

Providing context for an operation

Context is typically used to communicate between a request API (such as useQuery) and the links in the link chain. You provide context for a particular operation using the context option.

The following example provides the initial context with useQuery to define the initial count from the previous example.

1function MyComponent() {
2  const { data } = useQuery(MY_QUERY, { context: { count: 10 } });
3
4  // render data
5}