Data sources

Manage connections to databases and REST APIs

Data sources are classes that Apollo Server can use to encapsulate fetching data from a particular source, such as a database or a REST API. These classes help handle caching, deduplication, and errors while resolving operations.

Your server can use any number of different data sources. You don't have to use data sources to fetch data, but they're strongly recommended.

Open-source implementations

All data source implementations extend the generic DataSource abstract class, which is included in the apollo-datasource package. Subclasses of a DataSource should define whatever logic is required to communicate with a particular store or API.

Apollo and the larger community maintain the following open-source implementations:

Do you maintain a DataSource implementation that isn't listed here? Please submit a PR to be added to the list!

Class	Source	For Use With
`RESTDataSource`	Apollo	REST APIs (see below)
`HTTPDataSource`	Community	HTTP/REST APIs (newer community alternative to `RESTDataSource`)
`SQLDataSource`	Community	SQL databases (via Knex.js)
`MongoDataSource`	Community	MongoDB
`CosmosDataSource`	Community	Azure Cosmos DB
`FirestoreDataSource`	Community	Cloud Firestore

If none of these implementations applies to your use case, you can create your own custom DataSource subclass.

Apollo does not provide official support for community-maintained libraries. We cannot guarantee that community-maintained libraries adhere to best practices, or that they will continue to be maintained.

Adding data sources to Apollo Server

You provide your DataSource subclasses to the ApolloServer constructor, like so:

index.js

1
const server = new ApolloServer({
2
  typeDefs,
3
  resolvers,
4
  csrfPrevention: true,
5
  cache: "bounded",
6
  dataSources: () => {
7
    return {
8
      moviesAPI: new MoviesAPI(),
9
      personalizationAPI: new PersonalizationAPI(),
10
    };
11
  },
12
});

As shown, the dataSources option is a function. This function returns an object containing instances of your DataSource subclasses (in this case, MoviesAPI and PersonalizationAPI).
Apollo Server calls this function for every incoming operation. It automatically assigns the returned object to the dataSources field of the context object that's passed between your server's resolvers.
Also as shown, the function should create a new instance of each data source for each operation. If multiple operations share a single data source instance, you might accidentally combine results from multiple operations.

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

resolvers.js

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

By default, data source implementations use Apollo Server's in-memory cache to store the results of past fetches.

When you initialize Apollo Server, you can provide its constructor a different cache object that implements the KeyValueCache interface. This enables you to back your cache with shared stores like Memcached or Redis.

Using an external cache backend

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.

Apollo Server supports using Memcached, Redis, or other cache backends via the keyv package. For examples, see Configuring external caching.

You can also choose to implement your own cache backend. For more information, see Implementing your own cache backend.

`RESTDataSource` reference

The RESTDataSource abstract class helps you fetch data from REST APIs. Your server defines a separate subclass of RESTDataSource for each REST API it communicates with.

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

1
npm install apollo-datasource-rest

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

Example

Here's an example RESTDataSource subclass that defines two data-fetching methods, getMovie and getMostViewedMovies:

movies-api.js

1
const { RESTDataSource } = require('apollo-datasource-rest');
2

3
class MoviesAPI extends RESTDataSource {
4
  constructor() {
5
    // Always call super()
6
    super();
7
    // Sets the base URL for the REST API
8
    this.baseURL = 'https://movies-api.example.com/';
9
  }
10

11
  async getMovie(id) {
12
    // Send a GET request to the specified endpoint
13
    return this.get(`movies/${encodeURIComponent(id)}`);
14
  }
15

16
  async getMostViewedMovies(limit = 10) {
17
    const data = await this.get('movies', {
18
      // Query parameters
19
      per_page: limit,
20
      order_by: 'most_viewed',
21
    });
22
    return data.results;
23
  }
24
}

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. This is a standard JavaScript 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 depends on the HTTP method:

For HTTP methods with a request body (post, put, patch), the second parameter is the request body.
For HTTP methods without a request body, the second parameter is an object with keys and values corresponding to the request's query parameters.

For all methods, the third parameter is an init object that enables you to provide additional options (such as headers and referrers) to the fetch API that's used to send the request. For details, see MDN's fetch docs.

Intercepting fetches

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.

Setting a header

1
class PersonalizationAPI extends RESTDataSource {
2
  willSendRequest(request) {
3
    request.headers.set('Authorization', this.context.token);
4
  }
5
}

Adding a query parameter

1
class PersonalizationAPI extends RESTDataSource {
2
  willSendRequest(request) {
3
    request.params.set('api_key', this.context.token);
4
  }
5
}

Using with TypeScript

If you're using TypeScript, make sure to import the RequestOptions type:

1
import { RESTDataSource, RequestOptions } from 'apollo-datasource-rest';
2

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

6
  willSendRequest(request: RequestOptions) {
7
    request.headers.set('Authorization', this.context.token);
8
  }
9
}

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
async resolveURL(request: RequestOptions) {
2
  if (!this.baseURL) {
3
    const addresses = await resolveSrv(request.path.split("/")[1] + ".service.consul");
4
    this.baseURL = addresses[0];
5
  }
6
  return super.resolveURL(request);
7
}

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
class PersonalizationAPI extends RESTDataSource {
2
  constructor() {
3
    super();
4
    this.baseURL = 'https://personalization-api.example.com/';
5
  }
6

7
  willSendRequest(request) {
8
    request.headers.set('Authorization', this.context.token);
9
  }
10

11
  private progressLoader = new DataLoader(async (ids) => {
12
    const progressList = await this.get('progress', {
13
      ids: ids.join(','),
14
    });
15
    return ids.map(id =>
16
      progressList.find((progress) => progress.id === id),
17
    );
18
  });
19

20
  async getProgressFor(id) {
21
    return this.progressLoader.load(id);
22
  }

Edit on GitHub

Resolvers

Error handling