Fetching from REST

Using RESTDataSource to fetch data from REST APIs

See the @apollo/datasource-rest page for the full details of the RESTDataSource API.

The RESTDataSource class helps you fetch data from REST APIs. The RESTDataSource class helps handle caching, deduplication, and errors while resolving operations.

Creating subclasses

To get started, install the @apollo/datasource-rest package:

1
npm install @apollo/datasource-rest

Your server should define a separate subclass of RESTDataSource for each REST API it communicates with. Here's an example of a RESTDataSource subclass that defines two data-fetching methods, getMovie and getMostViewedMovies:

movies-api.ts

1
import { RESTDataSource } from '@apollo/datasource-rest';
2

3
class MoviesAPI extends RESTDataSource {
4
  override baseURL = 'https://movies-api.example.com/';
5

6
  async getMovie(id): Promise<Movie> {
7
    return this.get<Movie>(`movies/${encodeURIComponent(id)}`);
8
  }
9

10
  async getMostViewedMovies(limit = '10'): Promise<Movie[]> {
11
    const data = await this.get('movies', {
12
      params: {
13
        per_page: limit,
14
        order_by: 'most_viewed',
15
      },
16
    });
17
    return data.results;
18
  }
19
}

movies-api.js

1
import { RESTDataSource } from '@apollo/datasource-rest';
2

3
class MoviesAPI extends RESTDataSource {
4
  baseURL = 'https://movies-api.example.com/';
5

6
  async getMovie(id) {
7
    return this.get(`movies/${encodeURIComponent(id)}`);
8
  }
9

10
  async getMostViewedMovies(limit = '10') {
11
    const data = await this.get('movies', {
12
      params: {
13
        per_page: limit,
14
        order_by: 'most_viewed',
15
      },
16
    });
17

18
    return data.results;
19
  }
20
}

You can extend the RESTDataSource class to implement whatever data-fetching methods your resolvers need. These methods should use the built-in convenience methods (e.g., get and post) to perform HTTP requests, helping you add query parameters, parse and cache JSON results, dedupe requests, and handle errors.

Adding data sources to Apollo Server's context

You can add data sources to the context initialization function, like so:

index.ts

1
interface ContextValue {
2
  dataSources: {
3
    moviesAPI: MoviesAPI;
4
    personalizationAPI: PersonalizationAPI;
5
  };
6
}
7

8
const server = new ApolloServer<ContextValue>({
9
  typeDefs,
10
  resolvers,
11
});
12

13
const { url } = await startStandaloneServer(server, {
14
  context: async () => {
15
    const { cache } = server; 
16
    return {
17
      // We create new instances of our data sources with each request,
18
      // passing in our server's cache.
19
      dataSources: {
20
        moviesAPI: new MoviesAPI({ cache }),
21
        personalizationAPI: new PersonalizationAPI({ cache }),
22
      },
23
    };
24
  },
25
});
26

27
console.log(`🚀  Server ready at ${url}`);

index.js

1

2

3
const server = new ApolloServer({
4
  typeDefs,
5
  resolvers,
6
});
7

8
const { url } = await startStandaloneServer(server, {
9
  context: async () => {
10
    const { cache } = server; 
11
    return {
12
      // We create new instances of our data sources with each request,
13
      // passing in our server's cache.
14
      dataSources: {
15
        moviesAPI: new MoviesAPI({ cache }),
16
        personalizationAPI: new PersonalizationAPI({ cache }),
17
      },
18

19
    };
20
  },
21
});
22

23
console.log(`🚀  Server ready at ${url}`);

Apollo Server calls the context initialization function for every incoming operation. This means:

For every operation, context returns an object containing new instances of your RESTDataSource subclasses (in this case, MoviesAPI and PersonalizationAPI).
The context function should create a new instance of each RESTDataSource subclass for each operation.

Your resolvers can then access your data sources from the shared context object and use them to fetch data:

resolvers.ts

1
const resolvers = {
2
  Query: {
3
    movie: async (_, { id }, { dataSources }) => {
4
      return dataSources.moviesAPI.getMovie(id);
5
    },
6
    mostViewedMovies: async (_, __, { dataSources }) => {
7
      return dataSources.moviesAPI.getMostViewedMovies();
8
    },
9
    favorites: async (_, __, { dataSources }) => {
10
      return dataSources.personalizationAPI.getFavorites();
11
    },
12
  },
13
};

Caching

📣 New in Apollo Server 4: Apollo Server no longer automatically provides its cache to data sources. See here for more details.

The RESTDataSource class can cache results if the REST API it fetches from specifies caching headers in its HTTP responses (e.g., cache-control).

As shown in the above code snippet, by default, each RESTDataSource subclass accepts a cache argument (e.g., Apollo Server's default cache) to store the results of past fetches:

1
class MoviesAPI extends RESTDataSource {
2
  override baseURL = 'https://movies-api.example.com/';
3

4
  // We omit the constructor function here because
5
  // RESTDataSource accepts a cache argument by default
6
}
7

8
// server set up, etc.
9

10
const { url } = await startStandaloneServer(server, {
11
  context: async ({ req }) => {
12
    const { cache } = server; 
13
    return {
14
      dataSources: {
15
        moviesAPI: new MoviesAPI({ cache }),
16
        personalizationAPI: new PersonalizationAPI({ cache }),
17
      },
18
    };
19
  },
20
});

If your RESTDataSource subclass accepts multiple arguments, make sure you add a constructor function, like so:

1
import { ApolloServer } from '@apollo/server';
2
import { startStandaloneServer } from '@apollo/server/standalone';
3
import { RESTDataSource } from '@apollo/datasource-rest';
4
// KeyValueCache is the type of Apollo server's default cache
5
import type { KeyValueCache } from '@apollo/utils.keyvaluecache';
6

7
class PersonalizationAPI extends RESTDataSource {
8
  override baseURL = 'https://movies-api.example.com/';
9
  private token: string;
10

11
  constructor(options: { token: string; cache: KeyValueCache }) {
12
    super(options); // this sends our server's `cache` through
13
    this.token = options.token;
14
  }
15

16
  // data fetching methods, etc.
17
}
18

19
// set up server, context typing, etc.
20

21
const { url } = await startStandaloneServer(server, {
22
  context: async ({ req }) => {
23
    const token = getTokenFromRequest(req);
24
    const { cache } = server;
25
    return {
26
      dataSources: {
27
        personalizationApi: new PersonalizationAPI({ cache, token }),
28
      },
29
    };
30
  },
31
});

1
import { startStandaloneServer } from '@apollo/server/standalone';
2
import { RESTDataSource } from '@apollo/datasource-rest';
3
// KeyValueCache is the type of Apollo server's default cache
4

5
class PersonalizationAPI extends RESTDataSource {
6
  baseURL = 'https://movies-api.example.com/';
7

8
  constructor(options) {
9
    super(options); // this sends our server's `cache` through
10
    this.token = options.token;
11
  }
12

13
  // data fetching methods, etc.
14
}
15

16
// set up server, context typing, etc.
17

18
const { url } = await startStandaloneServer(server, {
19
  context: async ({ req }) => {
20
    const token = getTokenFromRequest(req);
21
    const { cache } = server;
22
    return {
23
      dataSources: {
24
        personalizationApi: new PersonalizationAPI({ cache, token }),
25
      },
26

27
    };
28
  },
29
});

When running multiple instances of your server, you should use a shared cache backend. This enables one server instance to use the cached result from another instance.

If you want to configure or replace Apollo Server's default cache, see Configuring external caching for more details.

HTTP Methods

RESTDataSource includes convenience methods for common REST API request methods: get, post, put, patch, and delete (see the source).

An example of each is shown below:

Note the use of encodeURIComponent in the above snippet. This is a standard function that encodes special characters in a URI, preventing a possible injection attack vector.

For a simple example, suppose our REST endpoint responded to the following URLs:

DELETE /movies/:id
DELETE /movies/:id/characters

A "malicious" client could provide an :id of 1/characters to target the delete characters endpoint when it was the singular movie endpoint that we were trying to delete. URI encoding prevents this kind of injection by transforming the / into %2F. This can then be correctly decoded and interpreted by the server and won't be treated as a path segment.

Method parameters

For all HTTP convenience methods, the first parameter is the relative path of the endpoint you're sending the request to (e.g., movies). The second parameter is an object where you can set a request's headers, params, cacheOptions, and body:

1
class MoviesAPI extends RESTDataSource {
2
  override baseURL = 'https://movies-api.example.com/';
3

4
  // an example making an HTTP POST request
5
  async postMovie(movie) {
6
    return this.post(
7
      `movies`, // path
8
      { body: movie }, // request body
9
    );
10
  }
11
}

Intercepting fetches

New in Apollo Server 4: Apollo Server 4 now uses the @apollo/utils.fetcher interface under the hood for fetching. This interface lets you choose your own implementation of the Fetch API. To ensure compatibility with all Fetch implementations, the request provided to hooks like willSendRequest is a plain JS object rather than a Request object with methods.

RESTDataSource includes a willSendRequest method that you can override to modify outgoing requests before they're sent. For example, you can use this method to add headers or query parameters. This method is most commonly used for authorization or other concerns that apply to all sent requests.

Data sources also have access to the GraphQL operation context, which is useful for storing a user token or other relevant information.

If you're using TypeScript, make sure to import the WillSendRequestOptions type.

Setting a header

1
import { RESTDataSource, WillSendRequestOptions } from '@apollo/datasource-rest';
2
import type { KeyValueCache } from '@apollo/utils.keyvaluecache';
3

4
class PersonalizationAPI extends RESTDataSource {
5
  override baseURL = 'https://movies-api.example.com/';
6
  private token: string;
7

8
  constructor(options: { token: string; cache: KeyValueCache }) {
9
    super(options);
10
    this.token = options.token;
11
  }
12

13
  override willSendRequest(request: WillSendRequestOptions) {
14
    request.headers['authorization'] = this.token;
15
  }
16
}

1
import { RESTDataSource } from '@apollo/datasource-rest';
2

3
class PersonalizationAPI extends RESTDataSource {
4
  baseURL = 'https://movies-api.example.com/';
5

6
  constructor(options) {
7
    super(options);
8
    this.token = options.token;
9
  }
10

11
  willSendRequest(request) {
12
    request.headers['authorization'] = this.token;
13
  }
14
}

Adding a query parameter

1
import { RESTDataSource, WillSendRequestOptions } from '@apollo/datasource-rest';
2
import type { KeyValueCache } from '@apollo/utils.keyvaluecache';
3

4
class PersonalizationAPI extends RESTDataSource {
5
  override baseURL = 'https://movies-api.example.com/';
6
  private token: string;
7

8
  constructor(options: { token: string; cache: KeyValueCache }) {
9
    super(options);
10
    this.token = options.token;
11
  }
12

13
  override willSendRequest(request: WillSendRequestOptions) {
14
    request.params.set('api_key', this.token);
15
  }
16
}

1
import { RESTDataSource } from '@apollo/datasource-rest';
2

3
class PersonalizationAPI extends RESTDataSource {
4
  baseURL = 'https://movies-api.example.com/';
5

6
  constructor(options) {
7
    super(options);
8
    this.token = options.token;
9
  }
10

11
  willSendRequest(request) {
12
    request.params.set('api_key', this.token);
13
  }
14
}

Resolving URLs dynamically

In some cases, you'll want to set the URL based on the environment or other contextual values. To do this, you can override resolveURL:

1
import { RESTDataSource, RequestOptions } from '@apollo/datasource-rest';
2
import type { KeyValueCache } from '@apollo/utils.keyvaluecache';
3

4
class PersonalizationAPI extends RESTDataSource {
5
  private token: string;
6

7
  constructor(options: { token: string; cache: KeyValueCache }) {
8
    super(options);
9
    this.token = options.token;
10
  }
11

12
  override async resolveURL(path: string, request: RequestOptions) {
13
    if (!this.baseURL) {
14
      const addresses = await resolveSrv(path.split('/')[1] + '.service.consul');
15
      this.baseURL = addresses[0];
16
    }
17
    return super.resolveURL(path, request);
18
  }
19
}

1
import { RESTDataSource } from '@apollo/datasource-rest';
2

3
class PersonalizationAPI extends RESTDataSource {
4
  constructor(options) {
5
    super(options);
6
    this.token = options.token;
7
  }
8

9
  async resolveURL(path, request) {
10
    if (!this.baseURL) {
11
      const addresses = await resolveSrv(
12
        path.split('/')[1] + '.service.consul',
13
      );
14
      this.baseURL = addresses[0];
15
    }
16
    return super.resolveURL(path, request);
17
  }
18
}

Using with DataLoader

The DataLoader utility was designed for a specific use case: deduplicating and batching object loads from a data store. It provides a memoization cache, which avoids loading the same object multiple times during a single GraphQL request. It also combines loads that occur during a single tick of the event loop into a batched request that fetches multiple objects at once.

DataLoader is great for its intended use case, but it’s less helpful when loading data from REST APIs. This is because its primary feature is batching, not caching.

When layering GraphQL over REST APIs, it's most helpful to have a resource cache that:

Saves data across multiple GraphQL requests
Can be shared across multiple GraphQL servers
Provides cache management features like expiry and invalidation that use standard HTTP cache control headers

Batching with REST APIs

Most REST APIs don't support batching. When they do, using a batched endpoint can jeopardize caching. When you fetch data in a batch request, the response you receive is for the exact combination of resources you're requesting. Unless you request that same combination again, future requests for the same resource won't be served from cache.

We recommend that you restrict batching to requests that can't be cached. In these cases, you can take advantage of DataLoader as a private implementation detail inside your RESTDataSource:

1
import DataLoader from 'dataloader';
2
import { RESTDataSource, WillSendRequestOptions } from '@apollo/datasource-rest';
3
import type { KeyValueCache } from '@apollo/utils.keyvaluecache';
4

5
class PersonalizationAPI extends RESTDataSource {
6
  override baseURL = 'https://movies-api.example.com/';
7
  private token: string;
8

9
  constructor(options: { token: string; cache: KeyValueCache }) {
10
    super(options); // this should send our server's `cache` through
11
    this.token = options.token;
12
  }
13

14
  override willSendRequest(request: WillSendRequestOptions) {
15
    request.headers['authorization'] = this.token;
16
  }
17

18
  private progressLoader = new DataLoader(async (ids) => {
19
    const progressList = await this.get('progress', { params: { ids: ids.join(',') } });
20
    return ids.map((id) => progressList.find((progress) => progress.id === id));
21
  });
22

23
  async getProgressFor(id) {
24
    return this.progressLoader.load(id);
25
  }
26
}

Edit on GitHub

Resolvers

Error handling