{"id":15962,"library":"apollo-link-http","title":"Apollo HTTP Link","description":"apollo-link-http is a foundational, terminating link within the Apollo Link ecosystem, designed to transport GraphQL queries, mutations, and subscriptions over standard HTTP. It serves as the primary method for connecting an Apollo Client instance to a GraphQL server via fetch. Currently at version 1.5.17, this package is considered stable but is part of the older `apollo-link` architecture, which has largely been superseded by integrated link implementations within `@apollo/client` v3 and newer. It supports both POST and GET requests and offers extensive options for dynamic URIs, custom headers, credentials, and fetch behavior, including per-query overrides via context. Its key differentiator is its modularity within the `apollo-link` chain, allowing it to be composed with other links for features like error handling, retries, or batching. It requires a `fetch` compatible API in the runtime environment.","status":"maintenance","version":"1.5.17","language":"javascript","source_language":"en","source_url":"https://github.com/apollographql/apollo-link","tags":["javascript","typescript"],"install":[{"cmd":"npm install apollo-link-http","lang":"bash","label":"npm"},{"cmd":"yarn add apollo-link-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add apollo-link-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for GraphQL type definitions and utilities.","package":"graphql","optional":false}],"imports":[{"note":"Primary factory function. While CommonJS `require` might technically work in older Node.js setups, modern Apollo Link usage strongly favors ESM imports.","wrong":"const { createHttpLink } = require('apollo-link-http');","symbol":"createHttpLink","correct":"import { createHttpLink } from 'apollo-link-http';"},{"note":"The class from which `createHttpLink` instantiates. Less commonly imported directly than `createHttpLink`.","symbol":"HttpLink","correct":"import { HttpLink } from 'apollo-link-http';"}],"quickstart":{"code":"import { ApolloClient, InMemoryCache } from '@apollo/client';\nimport { createHttpLink } from 'apollo-link-http';\nimport { setContext } from '@apollo/client/link/context';\n\n// Configure the HTTP link\nconst httpLink = createHttpLink({\n  uri: process.env.GRAPHQL_URI ?? '/graphql',\n});\n\n// Optionally, add an auth link to set headers dynamically\nconst authLink = setContext((_, { headers }) => {\n  // get the authentication token from local storage if it exists\n  const token = localStorage.getItem('token');\n  // return the headers to the context so httpLink can read them\n  return {\n    headers: {\n      ...headers,\n      authorization: token ? `Bearer ${token}` : \"\",\n    }\n  }\n});\n\n// Initialize Apollo Client with the composed link and a cache\nconst client = new ApolloClient({\n  link: authLink.concat(httpLink),\n  cache: new InMemoryCache()\n});\n\n// Example query using the client (requires @apollo/client to be installed)\n// import { gql } from '@apollo/client';\n// client.query({\n//   query: gql`\n//     query GetDogs {\n//       dogs {\n//         id\n//         breed\n//       }\n//     }\n//   `\n// }).then(result => console.log(result.data));","lang":"typescript","description":"Demonstrates initializing `apollo-link-http` and integrating it with Apollo Client, including dynamic headers."},"warnings":[{"fix":"Migrate to `import { HttpLink } from '@apollo/client/link/http';` and instantiate using `new HttpLink({ uri: '/graphql' });`.","message":"This package is part of the older `apollo-link` ecosystem. For new projects or when upgrading Apollo Client to v3 or higher, it is highly recommended to use the built-in HTTP link directly from `@apollo/client/link/http` instead of `apollo-link-http` to avoid potential compatibility issues and leverage modern features.","severity":"breaking","affected_versions":">=2.0.0 of @apollo/client"},{"fix":"For Node.js, use `node-fetch`: `import fetch from 'node-fetch'; const link = createHttpLink({ uri: '/graphql', fetch });`. For older browsers, use `unfetch` or a similar polyfill.","message":"The `apollo-link-http` relies on a global `fetch` API. In environments like Node.js or older browsers that lack native `fetch`, you must provide a polyfill or custom `fetch` implementation via the `fetch` option during link creation.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"If only queries should use GET, set `createHttpLink({ uri: '/graphql', useGETForQueries: true })`. If all requests should be GET, `createHttpLink({ uri: '/graphql', fetchOptions: { method: 'GET' } })` is acceptable, but be aware of GraphQL HTTP GET specification limitations for complex queries.","message":"Setting `fetchOptions.method: 'GET'` on the link's options or via context will force *all* requests (queries and mutations) to use GET. To only use GET for queries while keeping mutations as POST, use the `useGETForQueries: true` option at the top level.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be explicit about where dynamic options are set. For per-request dynamic values, use `apollo-link-context` to merge or override options into the context before the HTTP link processes them. For global defaults, set them directly on `createHttpLink`.","message":"Values provided in the `context` object (e.g., `context.headers`, `context.credentials`, `context.uri`, `context.fetchOptions`) will override any corresponding options initially set when creating the `HttpLink` instance. This is a powerful feature but can lead to unexpected behavior if not managed carefully, especially in multi-link chains.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Install and provide a `fetch` polyfill. For Node.js, install `node-fetch` (`npm install node-fetch`) and pass it to the link: `import fetch from 'node-fetch'; const link = createHttpLink({ uri: '/graphql', fetch });`.","cause":"The runtime environment (e.g., Node.js or older browser) does not natively support the `fetch` API, which `apollo-link-http` requires.","error":"ReferenceError: fetch is not defined"},{"fix":"Verify the `uri` option points to a valid and accessible GraphQL endpoint. Check browser console for CORS errors. Ensure the GraphQL server is running and accessible from the client's network location. Temporarily disable security software if testing locally.","cause":"Generic network error often due to incorrect URI, server being down, CORS issues, or firewall blocking the request.","error":"Error: Network error: Failed to fetch"},{"fix":"Ensure that your `ApolloClient` instance is correctly configured with a cache and a link. Verify that the GraphQL query or mutation string is valid and being passed correctly to `client.query()` or `client.mutate()`. If using `GET` for queries, ensure the query parameters are not exceeding URL length limits.","cause":"This error typically originates from the GraphQL server, indicating it received an empty or invalid GraphQL request, often a symptom of an issue with how the query or mutation is being sent by the client, or a malformed request body.","error":"GraphQL error: Must provide document"}],"ecosystem":"npm"}