gaxios

An HTTP request client that provides an axios like interface over top of node-fetch.

Install

1$ npm install gaxios

Example

1const {request} = require('gaxios');
2const res = await request({
3  url: 'https://www.googleapis.com/discovery/v1/apis/',
4});

Setting Defaults

Gaxios supports setting default properties both on the default instance, and on additional instances. This is often useful when making many requests to the same domain with the same base settings. For example:

1const gaxios = require('gaxios');
2gaxios.instance.defaults = {
3  baseURL: 'https://example.com'
4  headers: {
5    Authorization: 'SOME_TOKEN'
6  }
7}
8gaxios.request({url: '/data'}).then(...);

Note that setting default values will take precedence over other authentication methods, i.e., application default credentials.

Request Options

1interface GaxiosOptions = {
2  // The url to which the request should be sent.  Required.
3  url: string,
4
5  // The HTTP method to use for the request.  Defaults to `GET`.
6  method: 'GET',
7
8  // The base Url to use for the request. Prepended to the `url` property above.
9  baseURL: 'https://example.com';
10
11  // The HTTP methods to be sent with the request.
12  headers: { 'some': 'header' },
13
14  // The data to send in the body of the request. Data objects will be
15  // serialized as JSON.
16  //
17  // Note: if you would like to provide a Content-Type header other than
18  // application/json you you must provide a string or readable stream, rather
19  // than an object:
20  // data: JSON.stringify({some: 'data'})
21  // data: fs.readFile('./some-data.jpeg')
22  data: {
23    some: 'data'
24  },
25
26  // The max size of the http response content in bytes allowed.
27  // Defaults to `0`, which is the same as unset.
28  maxContentLength: 2000,
29
30  // The max number of HTTP redirects to follow.
31  // Defaults to 100.
32  maxRedirects: 100,
33
34  // The querystring parameters that will be encoded using `qs` and
35  // appended to the url
36  params: {
37    querystring: 'parameters'
38  },
39
40  // By default, we use the `querystring` package in node core to serialize
41  // querystring parameters.  You can override that and provide your
42  // own implementation.
43  paramsSerializer: (params) => {
44    return qs.stringify(params);
45  },
46
47  // The timeout for the HTTP request in milliseconds. Defaults to 0.
48  timeout: 1000,
49
50  // Optional method to override making the actual HTTP request. Useful
51  // for writing tests and instrumentation
52  adapter?: async (options, defaultAdapter) => {
53    const res = await defaultAdapter(options);
54    res.data = {
55      ...res.data,
56      extraProperty: 'your extra property',
57    };
58    return res;
59  };
60
61  // The expected return type of the request.  Options are:
62  // json | stream | blob | arraybuffer | text | unknown
63  // Defaults to `unknown`.
64  responseType: 'unknown',
65
66  // The node.js http agent to use for the request.
67  agent: someHttpsAgent,
68
69  // Custom function to determine if the response is valid based on the
70  // status code.  Defaults to (>= 200 && < 300)
71  validateStatus: (status: number) => true,
72
73  // Implementation of `fetch` to use when making the API call. By default,
74  // will use the browser context if available, and fall back to `node-fetch`
75  // in node.js otherwise.
76  fetchImplementation?: typeof fetch;
77
78  // Configuration for retrying of requests.
79  retryConfig: {
80    // The number of times to retry the request.  Defaults to 3.
81    retry?: number;
82
83    // The number of retries already attempted.
84    currentRetryAttempt?: number;
85
86    // The HTTP Methods that will be automatically retried.
87    // Defaults to ['GET','PUT','HEAD','OPTIONS','DELETE']
88    httpMethodsToRetry?: string[];
89
90    // The HTTP response status codes that will automatically be retried.
91    // Defaults to: [[100, 199], [408, 408], [429, 429], [500, 599]]
92    statusCodesToRetry?: number[][];
93
94    // Function to invoke when a retry attempt is made.
95    onRetryAttempt?: (err: GaxiosError) => Promise<void> | void;
96
97    // Function to invoke which determines if you should retry
98    shouldRetry?: (err: GaxiosError) => Promise<boolean> | boolean;
99
100    // When there is no response, the number of retries to attempt. Defaults to 2.
101    noResponseRetries?: number;
102
103    // The amount of time to initially delay the retry, in ms.  Defaults to 100ms.
104    retryDelay?: number;
105  },
106
107  // Enables default configuration for retries.
108  retry: boolean,
109
110  // Cancelling a request requires the `abort-controller` library.
111  // See https://github.com/bitinn/node-fetch#request-cancellation-with-abortsignal
112  signal?: AbortSignal
113
114  /**
115   * A collection of parts to send as a `Content-Type: multipart/related` request.
116   */
117  multipart?: GaxiosMultipartOptions;
118
119  /**
120   * An optional proxy to use for requests.
121   * Available via `process.env.HTTP_PROXY` and `process.env.HTTPS_PROXY` as well - with a preference for the this config option when multiple are available.
122   * The `agent` option overrides this.
123   *
124   * @see {@link GaxiosOptions.noProxy}
125   * @see {@link GaxiosOptions.agent}
126   */
127  proxy?: string | URL;
128  /**
129   * A list for excluding traffic for proxies.
130   * Available via `process.env.NO_PROXY` as well as a common-separated list of strings - merged with any local `noProxy` rules.
131   *
132   * - When provided a string, it is matched by
133   *   - Wildcard `*.` and `.` matching are available. (e.g. `.example.com` or `*.example.com`)
134   * - When provided a URL, it is matched by the `.origin` property.
135   *   - For example, requesting `https://example.com` with the following `noProxy`s would result in a no proxy use:
136   *     - new URL('https://example.com')
137   *     - new URL('https://example.com:443')
138   *   - The following would be used with a proxy:
139   *     - new URL('http://example.com:80')
140   *     - new URL('https://example.com:8443')
141   * - When provided a regular expression it is used to match the stringified URL
142   *
143   * @see {@link GaxiosOptions.proxy}
144   */
145  noProxy?: (string | URL | RegExp)[];
146
147  /**
148   * An experimental, customizable error redactor.
149   *
150   * Set `false` to disable.
151   *
152   * @remarks
153   *
154   * This does not replace the requirement for an active Data Loss Prevention (DLP) provider. For DLP suggestions, see:
155   * - https://cloud.google.com/sensitive-data-protection/docs/redacting-sensitive-data#dlp_deidentify_replace_infotype-nodejs
156   * - https://cloud.google.com/sensitive-data-protection/docs/infotypes-reference#credentials_and_secrets
157   *
158   * @experimental
159   */
160  errorRedactor?: typeof defaultErrorRedactor | false;
161}

License

Apache-2.0