Nomnom Pumpernickle Muffins

    @apollo/datasource-rest
    TypeScript icon, indicating that this package has built-in type declarations

    5.0.1 • Public • Published

    Apollo REST Data Source

    This package exports a (RESTDataSource) class which is used for fetching data from a REST API and exposing it via GraphQL within Apollo Server.

    RESTDataSource wraps an implementation of the DOM-style Fetch API such as node-fetch and adds the following features:

    • Two layers of caching:
      • An in-memory "request deduplication" feature which by default avoids sending the same GET (or HEAD) request multiple times in parallel.
      • An "HTTP cache" which provides browser-style caching in a (potentially shared) KeyValueCache which observes standard HTTP caching headers.
    • Convenience features such as the ability to specify an un-serialized object as a JSON request body and an easy way to specify URL search parameters
    • Error handling

    Documentation

    View the Apollo Server documentation for RESTDataSource for more high-level details and examples.

    Usage

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

    npm install @apollo/datasource-rest

    To define a data source, extend the RESTDataSource class and implement the data fetching methods that your resolvers require. Data sources can then be provided via Apollo Server's context object during execution.

    Your implementation of these methods can call convenience methods built into the RESTDataSource class to perform HTTP requests, while making it easy to build up query parameters, parse JSON results, and handle errors.

    const { RESTDataSource } = require('@apollo/datasource-rest');
    
    class MoviesAPI extends RESTDataSource {
      override baseURL = 'https://movies-api.example.com/';
    
      async getMovie(id) {
        return this.get(`movies/${encodeURIComponent(id)}`);
      }
    
      async getMostViewedMovies(limit = 10) {
        const data = await this.get('movies', {
          params: {
            per_page: limit.toString(), // all params entries should be strings
            order_by: 'most_viewed',
          },
        });
        return data.results;
      }
    }

    API Reference

    RESTDataSource is designed to be subclassed in order to create an API for use by the rest of your server. Many of its methods are protected. These consist of HTTP fetching methods (fetch, get, put, post, patch, delete, and head) which your API can call, and other methods that can be overridden to customize behavior.

    This README lists all the protected methods. In practice, if you're looking to customize behavior by overriding methods, reading the source code is the best option.

    Properties

    baseURL

    Optional value to use for all the REST calls. If it is set in your class implementation, this base URL is used as the prefix for all calls. If it is not set, then the value passed to the REST call is exactly the value used. See also resolveURL.

    class MoviesAPI extends RESTDataSource {
      override baseURL = 'https://movies-api.example.com/';
    
      // GET
      async getMovie(id) {
        return this.get(
          `movies/${encodeURIComponent(id)}` // path
        );
      }
    }

    RESTDataSource interprets the string passed to methods such as this.get() as an URL in exactly the same way that a browser interprets a link on a web page whose address is the same as this.baseURL. This may lead to slightly surprising behavior if this.baseURL has a non-empty path component:

    • If the string passed to a method such as this.get() starts with a slash, then it is resolved relative to the host of the base URL, not to the full base URL. That is, if this.baseURL is https://foo.com/a/b/c/, then this.get('d') resolves to https://foo.com/a/b/c/d, but this.get('/d') resolves to https://foo.com/d.
    • If the base URL has a path element and does not end in a slash, then the given path replaces the last element of the path. That is, if baseURL is https://foo.com/a/b/c, this.get('d') resolves to https://foo.com/a/b/d

    In practice, this means that you should usually set this.baseURL to the common prefix of all URLs you want to access including a trailing slash, and you should pass paths without a leading slash to methods such as this.get().

    If a resource's path starts with something that looks like an URL because it contains a colon and you want it to be added on to the full base URL after its path (so you can't pass it as this.get('/foo:bar')), you can pass a path starting with ./, like this.get('./foo:bar').

    httpCache

    This is an internal object that adds HTTP-header-sensitive caching to HTTP fetching. Its exact API is internal to this package and may change between versions.

    Overridable methods

    cacheKeyFor

    By default, RESTDatasource uses the cacheKey option from the request as the cache key, or the request method and full request URL otherwise when saving information about the request to the KeyValueCache. Override this method to remove query parameters or compute a custom cache key.

    For example, you could use this to use header fields or the HTTP method as part of the cache key. Even though we do validate header fields and don't serve responses from cache when they don't match, new responses overwrite old ones with different header fields. (For the HTTP method, this might be a positive thing, as you may want a POST /foo request to stop a previously cached GET /foo from being returned.)

    requestDeduplicationPolicyFor

    By default, RESTDataSource de-duplicates all concurrent outgoing GET (or HEAD) requests in an in-memory cache, separate from the KeyValueCache used for the HTTP response cache. It makes the assumption that two GET (or two HEAD) requests to the same URL made in parallel can share the same response. When the request returns, its response is delivered to each caller that requested the same URL concurrently, and then it is removed from the cache.

    If a request is made with the same cache key (method + URL by default) but with an HTTP method other than GET or HEAD, deduplication of the in-flight request is invalidated: the next parallel GET (or HEAD) request for the same URL will make a new request.

    You can configure this behavior in several ways:

    • You can change which requests are de-deduplicated and which are not.
    • You can tell RESTDataSource to de-duplicate a request against new requests that start after it completes, not just overlapping requests. (This was the poorly-documented behavior of RESTDataSource prior to v5.0.0.)
    • You can control the "deduplication key" independently from the KeyValueCache cache key.

    You do this by overriding the requestDeduplicationPolicyFor method in your class. This method takes an URL and a request, and returns a policy object with one of three forms:

    • {policy: 'deduplicate-during-request-lifetime', deduplicationKey: string}: This is the default behavior for GET requests. If a request with the same deduplication key is in progress, share its result. Otherwise, start a request, allow other requests to de-duplicate against it while it is running, and forget about it once the request returns successfully.
    • {policy: 'deduplicate-until-invalidated', deduplicationKey: string}: This was the default behavior for GET requests in versions prior to v5. If a request with the same deduplication key is in progress, share its result. Otherwise, start a request and allow other requests to de-duplicate against it while it is running. All future requests with policy deduplicate-during-request-lifetime or deduplicate-until-invalidated with the same deduplicationKey will share the same result until a request is started with policy do-not-deduplicate and a matching entry in invalidateDeduplicationKeys.
    • { policy: 'do-not-deduplicate'; invalidateDeduplicationKeys?: string[] }: This is the default behavior for non-GET requests. Always run an actual HTTP request and don't allow other requests to de-duplicate against it. Additionally, invalidate any listed keys immediately: new requests with that deduplicationKey will not match any requests that currently exist in the request cache.

    The default implementation of this method is:

    protected requestDeduplicationPolicyFor(
      url: URL,
      request: RequestOptions,
    ): RequestDeduplicationPolicy {
      const method = request.method ?? 'GET';
      // Start with the cache key that is used for the shared header-sensitive
      // cache. Note that its default implementation does not include the HTTP
      // method, so if a subclass overrides this and allows non-GET/HEADs to be
      // de-duplicated it will be important for it to include (at least!) the
      // method in the deduplication key, so we're explicitly adding GET/HEAD here.
      const cacheKey = this.cacheKeyFor(url, request);
      if (['GET', 'HEAD'].includes(method)) {
        return {
          policy: 'deduplicate-during-request-lifetime',
          deduplicationKey: `${method} ${cacheKey}`,
        };
      } else {
        return {
          policy: 'do-not-deduplicate',
          // Always invalidate GETs and HEADs when a different method is seen on the same
          // cache key (ie, URL), as per standard HTTP semantics. (We don't have
          // to invalidate the key with this HTTP method because we never write
          // it.)
          invalidateDeduplicationKeys: [
            this.cacheKeyFor(url, { ...request, method: 'GET' }),
            this.cacheKeyFor(url, { ...request, method: 'HEAD' }),
          ],
        };
      }

    To fully disable de-duplication, just always return do-not-duplicate. (This does not affect the HTTP header-sensitive cache.)

    class MoviesAPI extends RESTDataSource {
      protected override requestDeduplicationPolicyFor() {
        return { policy: 'do-not-deduplicate' } as const;
      }
    }
    willSendRequest

    This method is invoked at the beginning of processing each request. It's called with the path and request provided to fetch, with a guaranteed non-empty headers and params objects. If a Promise is returned from this method it will wait until the promise is completed to continue executing the request. See the intercepting fetches section for usage examples.

    resolveURL

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

    import type { KeyValueCache } from '@apollo/utils.keyvaluecache';
    
    class PersonalizationAPI extends RESTDataSource {
      override async resolveURL(path: string, _request: AugmentedRequest) {
        if (!this.baseURL) {
          const addresses = await resolveSrv(path.split("/")[1] + ".service.consul");
          this.baseURL = addresses[0];
        }
        return super.resolveURL(path);
      }
    }
    cacheOptionsFor

    Allows setting the CacheOptions to be used for each request/response in the HTTPCache. This is separate from the request-only cache. You can use this to set the TTL to a value in seconds. If you return {ttl: 0}, the response will not be stored. If you return a positive number for ttl and the operation returns a 2xx status code, then the response will be cached, regardless of HTTP headers: make sure this is what you intended! (There is currently no way to say "only cache responses that should be cached according to HTTP headers, but change the TTL to something specific".) Note that if you do not specify ttl here, only GET requests are cached.

    You can also specify cacheOptions as part of the "request" in any call to get(), post(), etc. Note that specifically head() calls are not cached at all, so this will have no effect for HEAD requests. This can either be an object such as {ttl: 1}, or a function returning that object. If cacheOptions is provided, cacheOptionsFor is not called (ie, this.cacheOptionsFor is effectively the default value of cacheOptions).

    The cacheOptions function and cacheOptionsFor method may be async.

    override cacheOptionsFor() {
      return {
        ttl: 1
      }
    }
    didEncounterError

    By default, this method just throws the error it was given. If you override this method, you can choose to either perform some additional logic and still throw, or to swallow the error by not throwing the error result.

    parseBody

    This method is called with the HTTP response and should read the body and parse it into an appropriate format. By default, it checks to see if the Content-Type header starts with application/json or ends with +json (just looking at the header as a string without using a Content-Type parser) and returns response.json() if it does or response.text() if it does not. If you want to read the body in a different way, override this. This method should read the response fully; if it does not, it could cause a memory leak inside the HTTP cache. If you override this, you may want to override cloneParsedBody as well.

    cloneParsedBody

    This method is used to clone a body (for use by the request deduplication feature so that multiple callers get distinct return values that can be separately mutated). If your parseBody returns values other than basic JSON objects, you might want to override this method too. You can also change this method to return its argument without cloning if your code that uses this class is OK with the values returned from deduplicated requests sharing state.

    shouldJSONSerializeBody

    By default, this method returns true if the request body is:

    • a plain object or an array
    • an object with a toJSON method (which isn't a Buffer or an instance of a class named FormData)

    You can override this method in order to serialize other objects such as custom classes as JSON.

    throwIfResponseIsError

    After the body is parsed, this method checks a condition (by default, if the HTTP status is 4xx or 5xx) and throws an error created with errorFromResponse if the condition is met.

    errorFromResponse

    Creates an error based on the response.

    catchCacheWritePromiseErrors

    This class writes to the shared HTTP-header-sensitive cache in the background (ie, the write is not awaited as part of the HTTP fetch). It passes the Promise associated with that cache write to this method. By default, this method adds a catch handler to the Promise which writes any errors to console.error. You could use this to do different error handling, or to do no error handling if you trust all callers to use the fetch method and await httpCache.cacheWritePromise.

    trace

    This method wraps the entire processing of a single request; if the NODE_ENV environment variable is equal to development, it logs the request method, URL, and duration. You can override this to provide observability in a different manner.

    HTTP Methods

    The get method on the RESTDataSource makes an HTTP GET request and returns its parsed body. Similarly, there are methods built-in to allow for POST, PUT, PATCH, DELETE, and HEAD requests. (The head method returns the full FetcherResponse rather than the body because HEAD responses do not have bodies.)

    class MoviesAPI extends RESTDataSource {
      override baseURL = 'https://movies-api.example.com/';
    
      // an example making an HTTP POST request
      async postMovie(movie) {
        return this.post(
          `movies`, // path
          { body: movie }, // request body
        );
      }
    
      // an example making an HTTP PUT request
      async newMovie(movie) {
        return this.put(
          `movies`, // path
          { body: movie }, // request body
        );
      }
    
      // an example making an HTTP PATCH request
      async updateMovie(movie) {
        return this.patch(
          `movies`, // path
          { body: { id: movie.id, movie } }, // request body
        );
      }
    
      // an example making an HTTP DELETE request
      async deleteMovie(movie) {
        return this.delete(
          `movies/${encodeURIComponent(movie.id)}`, // path
        );
      }
    }

    All of the HTTP helper functions (get, put, post, patch, delete, and head) accept a second parameter for setting the body, headers, params, cacheKey, and cacheOptions (and other Fetch API options).

    Alternatively, you can use the fetch method. The return value of this method is a DataSourceFetchResult, which contains parsedBody, response, and some other fields with metadata about how the operation interacted with the cache.

    Intercepting fetches

    Data sources allow you to intercept fetches to set headers, query parameters, or make other changes to the outgoing request. This is most often used for authorization or other common concerns that apply to all requests. Data sources also get access to the GraphQL context, which is a great place to store a user token or other information you need to have available.

    You can easily set a header on every request:

    class PersonalizationAPI extends RESTDataSource {
      willSendRequest(path, request) {
        request.headers['authorization'] = this.context.token;
      }
    }

    Or add a query parameter:

    class PersonalizationAPI extends RESTDataSource {
      willSendRequest(path, request) {
        request.params.set('api_key', this.context.token);
      }
    }

    If you're using TypeScript, you can use the AugmentedRequest type to define the willSendRequest signature:

    import { RESTDataSource, AugmentedRequest } from '@apollo/datasource-rest';
    
    class PersonalizationAPI extends RESTDataSource {
      override baseURL = 'https://personalization-api.example.com/';
    
      private token: string;
      constructor(options: { cache: KeyValueCache; token: string}) {
        super(options);
        this.token = options.token;
      }
    
      override willSendRequest(_path: string, request: AugmentedRequest) {
        request.headers['authorization'] = this.token;
      }
    }

    Integration with Apollo Server

    To give resolvers access to data sources, you create and return them from your context function. (The following example uses the Apollo Server 4 API.)

    interface MyContext {
      movies: MoviesAPI;
      personalization: PersonalizationAPI;
    }
    
    const server = new ApolloServer<MyContext>({
      typeDefs,
      resolvers,
    });
    
    // The context function you provide to your integration should handle constructing your data sources on every request.
    const url = await startStandaloneServer(server, {
      async context({ req }) { 
        return {
          moviesAPI: new MoviesAPI(),
          personalizationAPI: new PersonalizationAPI(req.headers['authorization']),
        };
      },
    });

    From our resolvers, we can access the data source from context and return the result:

    const resolvers = {
      Query: {
        movie: async (_source, { id }, { moviesAPI }) => {
          return moviesAPI.getMovie(id);
        },
        mostViewedMovies: async (_source, _args, { moviesAPI }) => {
          return moviesAPI.getMostViewedMovies();
        },
        favorites: async (_source, _args, { personalizationAPI }) => {
          return personalizationAPI.getFavorites();
        },
      },
    };

    Keywords

    none

    Install

    npm i @apollo/datasource-rest

    DownloadsWeekly Downloads

    11,224

    Version

    5.0.1

    License

    MIT

    Unpacked Size

    103 kB

    Total Files

    21

    Last publish

    Collaborators

    • dkuc
    • glasser
    • trevor.scheer
    • apollo-bot