Apollo-link-http

The http link is the most common Apollo Link, a system of modular components for GraphQL networking. If you haven't done so already, read the Apollo Link docs to learn about the Apollo Link ecosystem and how to use this link with libraries like Apollo Client and graphql-tools, or as a standalone client.

The http link is a terminating link that fetches GraphQL results from a GraphQL endpoint over an http connection. The http link supports both POST and GET requests with the ability to change the http options on a per query basis. This can be used for authentication, persisted queries, dynamic uris, and other granular updates.

Usage

Import and initialize this link in just two lines:

import { createHttpLink } from "apollo-link-http";
const link = createHttpLink({ uri: "/graphql" });

Options

HTTP Link takes an object with some options on it to customize the behavior of the link. If your server supports it, the HTTP link can also send over metadata about the request in the extensions field. To enable this, pass includeExtensions as true. The options you can pass are outlined below:

• uri: the URI key is a string endpoint or function resolving to an endpoint -- will default to "/graphql" if not specified
• includeExtensions: allow passing the extensions field to your graphql server, defaults to false
• fetch: a fetch compatible API for making a request
• headers: an object representing values to be sent as headers on the request
• credentials: a string representing the credentials policy you want for the fetch call. Possible values are: omit, include and same-origin
• fetchOptions: any overrides of the fetch options argument to pass to the fetch call
• useGETForQueries: set to true to use the HTTP GET method for queries (but not for mutations)

Fetch polyfill

The HTTP Link relies on having fetch present in your runtime environment. If you are running on react-native, or modern browsers, this should be no problem. If you are targeting an environment without fetch such as older browsers or the server, you will need to pass your own fetch to the link through the options. We recommend unfetch for older browsers and node-fetch for running in Node.

Context

The Http Link uses the headers field on the context to allow passing headers to the HTTP request. It also supports the credentials field for defining credentials policy, uri for changing the endpoint dynamically, and fetchOptions to allow generic fetch overrides (i.e. method: "GET"). These options will override the same key if passed when creating the the link.

Note that if you set fetchOptions.method to GET, the http link will follow the standard GraphQL HTTP GET encoding: the query, variables, operation name, and extensions will be passed as query parameters rather than in the HTTP request body. If you want mutations to continue to be sent as non-idempotent POST requests, set the top-level useGETForQueries option to true instead of setting fetchOptions.method to GET.

This link also attaches the response from the fetch operation on the context as response so you can access it from within another link.

• headers: an object representing values to be sent as headers on the request
• credentials: a string representing the credentials policy you want for the fetch call. Possible values are: omit, include and same-origin
• uri: a string of the endpoint you want to fetch from
• fetchOptions: any overrides of the fetch options argument to pass to the fetch call
• response: this is the raw response from the fetch request after it is made.
• http: this is an object to control fine grained aspects of the http link itself, such as persisted queries.

Persisted queries

The http link supports an advanced GraphQL feature called persisted queries. This allows you to not send the stringified query over the wire, but instead send some kind of identifier of the query. To support this you need to attach the id somewhere to the extensions field and pass the following options to the context:

operation.setContext({
  http: {
    includeExtensions: true,
    includeQuery: false,
  }
})

The http object on context currently supports two keys:

• includeExtensions: Send the extensions object for this request.
• includeQuery: Don't send the query field for this request.

One way to use persisted queries is with apollo-link-persisted-queries and Apollo Engine.

Passing context per query

Apollo Client supports passing context separately for every query, so you can do things like pass a special header for a single query invocation if you need to.

import { createHttpLink } from "apollo-link-http";
import ApolloClient from "apollo-client";
import { InMemoryCache } from "apollo-cache-inmemory";
const client = new ApolloClient({
  link: createHttpLink({ uri: "/graphql" }),
  cache: new InMemoryCache()
});
// a query with apollo-client
client.query({
  query: MY_QUERY,
  context: {
    // example of setting the headers with context per operation
    headers: {
      special: "Special header value"
    }
  }
});

Previous: Composing Links