HTTP Link
Get GraphQL results over a network using HTTP fetch.
We recommend reading Apollo Link overview before learning about individual links.
HttpLink
is a terminating link that sends a GraphQL operation to a remote endpoint over HTTP. Apollo Client uses HttpLink
by default when you provide the uri
option to the ApolloClient
constructor.
HttpLink
supports both POST and GET requests, and you can configure HTTP options on a per-operation basis. You can use these options for authentication, persisted queries, dynamic URIs, and other granular updates.
Usage
Import the HttpLink
class and initialize a link like so:
1import { HttpLink } from '@apollo/client';
2
3const link = new HttpLink({
4 uri: "http://localhost:4000/graphql"
5 // Additional options
6});
HttpLink
constructor options
The HttpLink
constructor takes an options object that can include the fields below. Note that you can also override some of these options on a per-operation basis using the operation context .
Name / Type |
Description |
---|---|
|
The URL of the GraphQL endpoint to send requests to. Can also be a function that accepts an The default value is |
|
If true, includes the The default value is |
|
A function to use instead of calling the Fetch API directly when sending HTTP requests to your GraphQL endpoint. The function must conform to the signature of By default, the Fetch API is used unless it isn't available in your runtime environment. See Customizing |
| An object representing headers to include in every HTTP request, such as |
|
If set to true, header names won't be automatically normalized to lowercase. This allows for non-http-spec-compliant servers that might expect capitalized header names. The default value is |
| The credentials policy to use for each |
| An object containing options to use for each call to Note that if you set |
| If The default value is |
| An optional function to use when transforming a query or mutation JavaScript
By default the bare GraphQL |
Context options
HttpLink
checks the current operation's context
for certain values before sending its request to your GraphQL endpoint. Previous links in the link chain can set these values to customize the behavior of HttpLink
for each operation.
Some of these values can also be provided as options to the
HttpLink
constructor . If a value is provided to both, the value in thecontext
takes precedence.
Name / Type |
Description |
---|---|
|
The URL of the GraphQL endpoint to send requests to. Can also be a function that accepts an The default value is |
| An object representing headers to include in the HTTP request, such as |
| The credentials policy to use for this |
| An object containing options to use for this call to Note that if you set |
|
An object that configures advanced |
http
option fields
Name / Type |
Description |
---|---|
|
If true, includes the The default value is |
|
If The default value is |
|
If set to true, header names won't be automatically normalized to lowercase. This allows for non-http-spec-compliant servers that might expect capitalized header names. The default value is |
Operation results
After your GraphQL endpoint (successfully) responds with the result of the sent operation, HttpLink
sets it as the response
field of the operation context
. This enables each previous link in your link chain to interact with the response before it's returned.
Handling errors
HttpLink
distinguishes between client errors, server errors, and GraphQL errors. You can add the onError
link to your link chain to handle these errors via a callback .
The following types of errors can occur:
Error | Description | Callback | Error Type |
---|---|---|---|
Client Parse | The request body is not serializable, for example due to a circular reference. | error | ClientParseError |
Server Parse | The server's response cannot be parsed (response.json() ) | error | ServerParseError |
Server Network | The server responded with a non-2xx HTTP code. | error | ServerError |
Server Data | The server's response didn't contain data or errors . | error | ServerError |
GraphQL Error | Resolving the GraphQL operation resulted in at least one error, which is present in the errors field. | next | Object |
Because many server implementations can return a valid GraphQL result on a server network error, the thrown Error
object contains the parsed server result. A server data error also receives the parsed result.
All error types inherit the name
, message
, and nullable stack
properties from the generic javascript Error :
1//type ClientParseError
2{
3 parseError: Error; // Error returned from response.json()
4};
5
6//type ServerParseError
7{
8 response: Response; // Object returned from fetch()
9 statusCode: number; // HTTP status code
10 bodyText: string // text that was returned from server
11};
12
13//type ServerError
14{
15 result: Record<string, any>; // Parsed object from server response
16 response: Response; // Object returned from fetch()
17 statusCode: number; // HTTP status code
18};
Customizing fetch
You can provide the fetch
option to the HttpLink
constructor to enable many custom networking needs. For example, you can modify the request based on calculated headers or calculate the endpoint URI based on the operation's details.
If you're targeting an environment that doesn't provide the Fetch API (such as older browsers or the server) you can provide a different implementation of fetch
. We recommend unfetch
for older browsers and node-fetch
for running in Node.
Custom auth
This example adds a custom Authorization
header to every request before calling fetch
:
1const customFetch = (uri, options) => {
2 const { header } = Hawk.client.header(
3 "http://example.com:8000/resource/1?b=1&a=2",
4 "POST",
5 { credentials: credentials, ext: "some-app-data" }
6 );
7 options.headers.Authorization = header;
8 return fetch(uri, options);
9};
10
11const link = new HttpLink({ fetch: customFetch });
Dynamic URI
This example customizes the endpoint URL's query parameters before calling fetch
:
1const customFetch = (uri, options) => {
2 const { operationName } = JSON.parse(options.body);
3 return fetch(`${uri}/graph/graphql?opname=${operationName}`, options);
4};
5
6const link = new HttpLink({ fetch: customFetch });