Apollo HTTP Data Source

Common errors

• Error: Cannot find module 'apollo-datasource-http'

  cause The `apollo-datasource-http` package has not been installed or is not resolvable in the current environment.
  fix Run `npm install apollo-datasource-http` or `yarn add apollo-datasource-http` to install the package.

• Error: dataSources must be a function which returns an object or a Promise which resolves to an object.

  cause The `dataSources` property in the `ApolloServer` constructor was not provided as a function that returns the data source instances.
  fix Ensure your `dataSources` configuration is a function, e.g., `dataSources: () => ({ moviesAPI: new MoviesAPI(baseURL, pool) })`.

• npm ERR! ERESOLVE unable to resolve dependency tree (or similar peer dependency warning for 'graphql')

  cause Your project's `graphql` version conflicts with the peer dependency requirement of `apollo-datasource-http`.
  fix Update your `graphql` package to a compatible version (e.g., `npm install graphql@16`) or adjust your dependency resolution strategy to satisfy the `^15.3.0 || ^16.0.0` range.

Warnings

• breaking This package is explicitly declared as pre-1.0 according to SemVer. This means that minor versions (e.g., 0.x.0 to 0.y.0) may introduce breaking changes without prior warning.
  Fix: Always review release notes for new versions before upgrading and be prepared for potential API changes even in minor updates.
• gotcha To achieve the advertised performance benefits, you must explicitly initialize and pass an `undici.Pool` instance to the `HTTPDataSource` constructor. Failing to do so will result in each request creating a new Undici client, negating performance optimizations.
  Fix: Instantiate `new Pool(baseURL)` once per unique base URL (ideally outside of the request hotpath) and pass it to your `HTTPDataSource` subclass constructor.
• breaking Version 0.18.0 introduced significant updates for compatibility with Apollo Server 3 and GraphQL 16. Older versions of Apollo Server or GraphQL might not function correctly with `apollo-datasource-http` versions 0.18.0 or newer.
  Fix: Ensure your project's `graphql` peer dependency is within the `^15.3.0 || ^16.0.0` range. If using older Apollo Server versions, you might need to stick to an older `apollo-datasource-http` release.

Install

• npm install apollo-datasource-http npm
• yarn add apollo-datasource-http yarn
• pnpm add apollo-datasource-http pnpm

Imports

• HTTPDataSource
  wrong:

  const HTTPDataSource = require('apollo-datasource-http')

  correct:

  import { HTTPDataSource } from 'apollo-datasource-http'

  Primarily designed for ES Modules. For CommonJS, dynamic import or a build-time transpilation strategy is typically required.
• Pool
  wrong:

  import { Pool } from 'apollo-datasource-http'

  correct:

  import { Pool } from 'undici'

  The Undici `Pool` is a crucial dependency for performance, but it must be imported directly from 'undici' and instantiated separately, then passed to the `HTTPDataSource` constructor.

Quickstart

Demonstrates how to extend `HTTPDataSource` to create a custom data source, configure it with `undici.Pool`, and implement methods for making cached GET and POST requests within an Apollo Server setup.

import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { Pool } from 'undici';
import { HTTPDataSource } from 'apollo-datasource-http';

const typeDefs = `#graphql
  type Movie {
    id: ID!
    name: String
  }

  type Query {
    movie(id: ID!): Movie
  }

  type Mutation {
    createMovie(name: String!): Movie
  }
`;

const baseURL = 'https://movies-api.example.com'; // Replace with your actual API base URL
const pool = new Pool(baseURL);

class MoviesAPI extends HTTPDataSource {
  constructor(baseURL: string, pool: Pool) {
    super(baseURL, { pool });
  }

  async createMovie(name: string) {
    return this.post('/movies', {
      body: { name }
    });
  }

  async getMovie(id: string) {
    return this.get(`/movies/${id}`, {
      context: { tracingName: 'getMovie' },
      requestCache: {
        maxTtl: 10 * 60, // 10min, will respond for 10min with the cached result
        maxTtlIfError: 30 * 60 // 30min, will respond with cached response in case of error
      }
    });
  }
}

const resolvers = {
  Query: {
    movie: async (_, { id }, { dataSources }) => {
      return dataSources.moviesAPI.getMovie(id);
    }
  },
  Mutation: {
    createMovie: async (_, { name }, { dataSources }) => {
      return dataSources.moviesAPI.createMovie(name);
    }
  }
};

const server = new ApolloServer({
  typeDefs,
  resolvers,
});

startStandaloneServer(server, {
  listen: { port: 4000 },
  context: async ({ req, res }) => ({
    dataSources: {
      moviesAPI: new MoviesAPI(baseURL, pool),
    },
  }),
}).then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});