UNPKG

19.4 kBMarkdownView Raw
1<div align="center">
2 <br>
3 <br>
4 <img width="360" src="media/logo.svg" alt="Got">
5 <br>
6 <br>
7 <br>
8 <p align="center">Huge thanks to <a href="https://moxy.studio"><img src="https://sindresorhus.com/assets/thanks/moxy-logo.svg" width="150"></a> for sponsoring me!
9 </p>
10 <br>
11 <br>
12</div>
13
14> Simplified HTTP requests
15
16[![Build Status](https://travis-ci.org/sindresorhus/got.svg?branch=master)](https://travis-ci.org/sindresorhus/got) [![Coverage Status](https://coveralls.io/repos/github/sindresorhus/got/badge.svg?branch=master)](https://coveralls.io/github/sindresorhus/got?branch=master) [![Downloads](https://img.shields.io/npm/dm/got.svg)](https://npmjs.com/got)
17
18A nicer interface to the built-in [`http`](http://nodejs.org/api/http.html) module.
19
20Created because [`request`](https://github.com/request/request) is bloated *(several megabytes!)*.
21
22
23## Highlights
24
25- [Promise & stream API](#api)
26- [Request cancelation](#aborting-the-request)
27- [RFC compliant caching](#cache-adapters)
28- [Follows redirects](#followredirect)
29- [Retries on network failure](#retries)
30- [Progress events](#onuploadprogress-progress)
31- [Handles gzip/deflate](#decompress)
32- [Timeout handling](#timeout)
33- [Errors with metadata](#errors)
34- [JSON mode](#json)
35- [WHATWG URL support](#url)
36- [Electron support](#useelectronnet)
37
38
39## Install
40
41```
42$ npm install got
43```
44
45<a href="https://www.patreon.com/sindresorhus">
46 <img src="https://c5.patreon.com/external/logo/become_a_patron_button@2x.png" width="160">
47</a>
48
49
50## Usage
51
52```js
53const got = require('got');
54
55(async () => {
56 try {
57 const response = await got('sindresorhus.com');
58 console.log(response.body);
59 //=> '<!doctype html> ...'
60 } catch (error) {
61 console.log(error.response.body);
62 //=> 'Internal server error ...'
63 }
64})();
65```
66
67###### Streams
68
69```js
70const fs = require('fs');
71const got = require('got');
72
73got.stream('sindresorhus.com').pipe(fs.createWriteStream('index.html'));
74
75// For POST, PUT, and PATCH methods `got.stream` returns a `stream.Writable`
76fs.createReadStream('index.html').pipe(got.stream.post('sindresorhus.com'));
77```
78
79
80### API
81
82It's a `GET` request by default, but can be changed by using different methods or in the `options`.
83
84#### got(url, [options])
85
86Returns a Promise for a `response` object with a `body` property, a `url` property with the request URL or the final URL after redirects, and a `requestUrl` property with the original request URL.
87
88The response object will normally be a [Node.js HTTP response stream](https://nodejs.org/api/http.html#http_class_http_incomingmessage), however if returned from the cache it will be a [responselike object](https://github.com/lukechilds/responselike) which behaves in the same way.
89
90The response will also have a `fromCache` property set with a boolean value.
91
92##### url
93
94Type: `string` `Object`
95
96The URL to request as simple string, a [`http.request` options](https://nodejs.org/api/http.html#http_http_request_options_callback), or a [WHATWG `URL`](https://nodejs.org/api/url.html#url_class_url).
97
98Properties from `options` will override properties in the parsed `url`.
99
100If no protocol is specified, it will default to `https`.
101
102##### options
103
104Type: `Object`
105
106Any of the [`http.request`](http://nodejs.org/api/http.html#http_http_request_options_callback) options.
107
108###### stream
109
110Type: `boolean`<br>
111Default: `false`
112
113Returns a `Stream` instead of a `Promise`. This is equivalent to calling `got.stream(url, [options])`.
114
115###### body
116
117Type: `string` `Buffer` `stream.Readable`
118
119*This is mutually exclusive with stream mode.*
120
121Body that will be sent with a `POST` request.
122
123If present in `options` and `options.method` is not set, `options.method` will be set to `POST`.
124
125If `content-length` or `transfer-encoding` is not set in `options.headers` and `body` is a string or buffer, `content-length` will be set to the body length.
126
127###### encoding
128
129Type: `string` `null`<br>
130Default: `'utf8'`
131
132[Encoding](https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings) to be used on `setEncoding` of the response data. If `null`, the body is returned as a [`Buffer`](https://nodejs.org/api/buffer.html) (binary data).
133
134###### form
135
136Type: `boolean`<br>
137Default: `false`
138
139*This is mutually exclusive with stream mode.*
140
141If set to `true` and `Content-Type` header is not set, it will be set to `application/x-www-form-urlencoded`.
142
143`body` must be a plain object or array and will be stringified.
144
145###### json
146
147Type: `boolean`<br>
148Default: `false`
149
150*This is mutually exclusive with stream mode.*
151
152If set to `true` and `Content-Type` header is not set, it will be set to `application/json`.
153
154Parse response body with `JSON.parse` and set `accept` header to `application/json`. If used in conjunction with the `form` option, the `body` will the stringified as querystring and the response parsed as JSON.
155
156`body` must be a plain object or array and will be stringified.
157
158###### query
159
160Type: `string` `Object`<br>
161
162Query string object that will be added to the request URL. This will override the query string in `url`.
163
164###### timeout
165
166Type: `number` `Object`
167
168Milliseconds to wait for the server to end the response before aborting request with `ETIMEDOUT` error.
169
170This also accepts an object with separate `connect`, `socket`, and `request` fields for connection, socket, and entire request timeouts.
171
172###### retries
173
174Type: `number` `Function`<br>
175Default: `2`
176
177Number of request retries when network errors happens. Delays between retries counts with function `1000 * Math.pow(2, retry) + Math.random() * 100`, where `retry` is attempt number (starts from 0).
178
179Option accepts `function` with `retry` and `error` arguments. Function must return delay in milliseconds (`0` return value cancels retry).
180
181**Note:** if `retries` is `number`, `ENOTFOUND` and `ENETUNREACH` error will not be retried (see full list in [`is-retry-allowed`](https://github.com/floatdrop/is-retry-allowed/blob/master/index.js#L12) module).
182
183###### followRedirect
184
185Type: `boolean`<br>
186Default: `true`
187
188Defines if redirect responses should be followed automatically.
189
190Note that if a `303` is sent by the server in response to any request type (`POST`, `DELETE`, etc.), got will automatically
191request the resource pointed to in the location header via `GET`. This is in accordance with [the spec](https://tools.ietf.org/html/rfc7231#section-6.4.4).
192
193###### decompress
194
195Type: `boolean`<br>
196Default: `true`
197
198Decompress the response automatically. This will set the `accept-encoding` header to `gzip, deflate` unless you set it yourself.
199
200If this is disabled, a compressed response is returned as a `Buffer`. This may be useful if you want to handle decompression yourself or stream the raw compressed data.
201
202###### cache
203
204Type: `Object`<br>
205Default: `false`
206
207[Cache adapter instance](#cache-adapters) for storing cached data.
208
209###### useElectronNet
210
211Type: `boolean`<br>
212Default: `false`
213
214When used in Electron, Got will use [`electron.net`](https://electronjs.org/docs/api/net/) instead of the Node.js `http` module. According to the Electron docs, it should be fully compatible, but it's not entirely. See [#315](https://github.com/sindresorhus/got/issues/315).
215
216###### throwHttpErrors
217
218Type: `boolean`<br>
219Default: `true`
220
221Determines if a `got.HTTPError` is thrown for error responses (non-2xx status codes).
222
223If this is disabled, requests that encounter an error status code will be resolved with the `response` instead of throwing. This may be useful if you are checking for resource availability and are expecting error responses.
224
225#### Streams
226
227#### got.stream(url, [options])
228
229`stream` method will return Duplex stream with additional events:
230
231##### .on('request', request)
232
233`request` event to get the request object of the request.
234
235**Tip**: You can use `request` event to abort request:
236
237```js
238got.stream('github.com')
239 .on('request', req => setTimeout(() => req.abort(), 50));
240```
241
242##### .on('response', response)
243
244`response` event to get the response object of the final request.
245
246##### .on('redirect', response, nextOptions)
247
248`redirect` event to get the response object of a redirect. The second argument is options for the next request to the redirect location.
249
250##### .on('uploadProgress', progress)
251##### .on('downloadProgress', progress)
252
253Progress events for uploading (sending request) and downloading (receiving response). The `progress` argument is an object like:
254
255```js
256{
257 percent: 0.1,
258 transferred: 1024,
259 total: 10240
260}
261```
262
263If it's not possible to retrieve the body size (can happen when streaming), `total` will be `null`.
264
265**Note**: Progress events can also be used with promises.
266
267```js
268(async () => {
269 const response = await got('sindresorhus.com')
270 .on('downloadProgress', progress => {
271 // Report download progress
272 })
273 .on('uploadProgress', progress => {
274 // Report upload progress
275 });
276
277 console.log(response);
278})();
279```
280
281##### .on('error', error, body, response)
282
283`error` event emitted in case of protocol error (like `ENOTFOUND` etc.) or status error (4xx or 5xx). The second argument is the body of the server response in case of status error. The third argument is response object.
284
285#### got.get(url, [options])
286#### got.post(url, [options])
287#### got.put(url, [options])
288#### got.patch(url, [options])
289#### got.head(url, [options])
290#### got.delete(url, [options])
291
292Sets `options.method` to the method name and makes a request.
293
294
295## Errors
296
297Each error contains (if available) `statusCode`, `statusMessage`, `host`, `hostname`, `method`, `path`, `protocol` and `url` properties to make debugging easier.
298
299In Promise mode, the `response` is attached to the error.
300
301#### got.CacheError
302
303When a cache method fails, for example if the database goes down, or there's a filesystem error.
304
305#### got.RequestError
306
307When a request fails. Contains a `code` property with error class code, like `ECONNREFUSED`.
308
309#### got.ReadError
310
311When reading from response stream fails.
312
313#### got.ParseError
314
315When `json` option is enabled, server response code is 2xx, and `JSON.parse` fails.
316
317#### got.HTTPError
318
319When server response code is not 2xx. Includes `statusCode`, `statusMessage`, and `redirectUrls` properties.
320
321#### got.MaxRedirectsError
322
323When server redirects you more than 10 times. Includes a `redirectUrls` property, which is an array of the URLs Got was redirected to before giving up.
324
325#### got.UnsupportedProtocolError
326
327When given an unsupported protocol.
328
329#### got.CancelError
330
331When the request is aborted with `.cancel()`.
332
333
334## Aborting the request
335
336The promise returned by Got has a [`.cancel()`](https://github.com/sindresorhus/p-cancelable) method which, when called, aborts the request.
337
338```js
339(async () => {
340 const request = got(url, options);
341
342 …
343
344 // In another part of the code
345 if (something) {
346 request.cancel();
347 }
348
349 …
350
351 try {
352 await request;
353 } catch (error) {
354 if (request.isCanceled) { // Or `error instanceof got.CancelError`
355 // Handle cancelation
356 }
357
358 // Handle other errors
359 }
360})();
361```
362
363<a name="cache-adapters"></a>
364## Cache
365
366Got implements [RFC 7234](http://httpwg.org/specs/rfc7234.html) compliant HTTP caching which works out of the box in memory or is easily pluggable with a wide range of storage adapters. Fresh cache entries are served directly from cache and stale cache entries are revalidated with `If-None-Match`/`If-Modified-Since` headers. You can read more about the underlying cache behaviour in the `cacheable-request` [documentation](https://github.com/lukechilds/cacheable-request).
367
368You can use the JavaScript `Map` type as an in memory cache:
369
370```js
371const got = require('got');
372const map = new Map();
373
374(async () => {
375 let response = await got('sindresorhus.com', {cache: map});
376 console.log(response.fromCache);
377 //=> false
378
379 response = await got('sindresorhus.com', {cache: map});
380 console.log(response.fromCache);
381 //=> true
382})();
383```
384
385Got uses [Keyv](https://github.com/lukechilds/keyv) internally to support a wide range of storage adapters. For something more scalable you could use an [official Keyv storage adapter](https://github.com/lukechilds/keyv#official-storage-adapters):
386
387```
388$ npm install @keyv/redis
389```
390
391```js
392const got = require('got');
393const KeyvRedis = require('@keyv/redis');
394
395const redis = new KeyvRedis('redis://user:pass@localhost:6379');
396
397got('sindresorhus.com', {cache: redis});
398```
399
400Got supports anything that follows the Map API, so it's easy to write your own storage adapter or use a third-party solution.
401
402For example, the following are all valid storage adapters:
403
404```js
405const storageAdapter = new Map();
406// or
407const storageAdapter = require('./my-storage-adapter');
408// or
409const QuickLRU = require('quick-lru');
410const storageAdapter = new QuickLRU({maxSize: 1000});
411
412got('sindresorhus.com', {cache: storageAdapter});
413```
414
415View the [Keyv docs](https://github.com/lukechilds/keyv) for more information on how to use storage adapters.
416
417
418## Proxies
419
420You can use the [`tunnel`](https://github.com/koichik/node-tunnel) module with the `agent` option to work with proxies:
421
422```js
423const got = require('got');
424const tunnel = require('tunnel');
425
426got('sindresorhus.com', {
427 agent: tunnel.httpOverHttp({
428 proxy: {
429 host: 'localhost'
430 }
431 })
432});
433```
434
435If you require different agents for different protocols, you can pass a map of agents to the `agent` option. This is necessary because a request to one protocol might redirect to another. In such a scenario, `got` will switch over to the right protocol agent for you.
436
437```js
438const got = require('got');
439const HttpAgent = require('agentkeepalive');
440const HttpsAgent = HttpAgent.HttpsAgent;
441
442got('sindresorhus.com', {
443 agent: {
444 http: new HttpAgent(),
445 https: new HttpsAgent()
446 }
447});
448```
449
450
451## Cookies
452
453You can use the [`cookie`](https://github.com/jshttp/cookie) module to include cookies in a request:
454
455```js
456const got = require('got');
457const cookie = require('cookie');
458
459got('google.com', {
460 headers: {
461 cookie: cookie.serialize('foo', 'bar')
462 }
463});
464```
465
466
467## Form data
468
469You can use the [`form-data`](https://github.com/form-data/form-data) module to create POST request with form data:
470
471```js
472const fs = require('fs');
473const got = require('got');
474const FormData = require('form-data');
475const form = new FormData();
476
477form.append('my_file', fs.createReadStream('/foo/bar.jpg'));
478
479got.post('google.com', {
480 body: form
481});
482```
483
484
485## OAuth
486
487You can use the [`oauth-1.0a`](https://github.com/ddo/oauth-1.0a) module to create a signed OAuth request:
488
489```js
490const got = require('got');
491const crypto = require('crypto');
492const OAuth = require('oauth-1.0a');
493
494const oauth = OAuth({
495 consumer: {
496 key: process.env.CONSUMER_KEY,
497 secret: process.env.CONSUMER_SECRET
498 },
499 signature_method: 'HMAC-SHA1',
500 hash_function: (baseString, key) => crypto.createHmac('sha1', key).update(baseString).digest('base64')
501});
502
503const token = {
504 key: process.env.ACCESS_TOKEN,
505 secret: process.env.ACCESS_TOKEN_SECRET
506};
507
508const url = 'https://api.twitter.com/1.1/statuses/home_timeline.json';
509
510got(url, {
511 headers: oauth.toHeader(oauth.authorize({url, method: 'GET'}, token)),
512 json: true
513});
514```
515
516
517## Unix Domain Sockets
518
519Requests can also be sent via [unix domain sockets](http://serverfault.com/questions/124517/whats-the-difference-between-unix-socket-and-tcp-ip-socket). Use the following URL scheme: `PROTOCOL://unix:SOCKET:PATH`.
520
521- `PROTOCOL` - `http` or `https` *(optional)*
522- `SOCKET` - absolute path to a unix domain socket, e.g. `/var/run/docker.sock`
523- `PATH` - request path, e.g. `/v2/keys`
524
525```js
526got('http://unix:/var/run/docker.sock:/containers/json');
527
528// or without protocol (http by default)
529got('unix:/var/run/docker.sock:/containers/json');
530```
531
532## AWS
533
534Requests to AWS services need to have their headers signed. This can be accomplished by using the [`aws4`](https://www.npmjs.com/package/aws4) package. This is an example for querying an ["Elasticsearch Service"](https://aws.amazon.com/elasticsearch-service/) host with a signed request.
535
536```js
537const url = require('url');
538const AWS = require('aws-sdk');
539const aws4 = require('aws4');
540const got = require('got');
541const config = require('./config');
542
543// Reads keys from the environment or `~/.aws/credentials`. Could be a plain object.
544const awsConfig = new AWS.Config({ region: config.region });
545
546function request(uri, options) {
547 const awsOpts = {
548 region: awsConfig.region,
549 headers: {
550 accept: 'application/json',
551 'content-type': 'application/json'
552 },
553 method: 'GET',
554 json: true
555 };
556
557 // We need to parse the URL before passing it to `got` so `aws4` can sign the request
558 const opts = Object.assign(url.parse(uri), awsOpts, options);
559 aws4.sign(opts, awsConfig.credentials);
560
561 return got(opts);
562}
563
564request(`https://${config.host}/production/users/1`);
565
566request(`https://${config.host}/production/`, {
567 // All usual `got` options
568});
569```
570
571
572## Testing
573
574You can test your requests by using the [`nock`](https://github.com/node-nock/nock) module to mock an endpoint:
575
576```js
577const got = require('got');
578const nock = require('nock');
579
580nock('https://sindresorhus.com')
581 .get('/')
582 .reply(200, 'Hello world!');
583
584(async () => {
585 const response = await got('sindresorhus.com');
586 console.log(response.body);
587 //=> 'Hello world!'
588})();
589```
590
591If you need real integration tests you can use [`create-test-server`](https://github.com/lukechilds/create-test-server):
592
593```js
594const got = require('got');
595const createTestServer = require('create-test-server');
596
597(async () => {
598 const server = await createTestServer();
599 server.get('/', 'Hello world!');
600
601 const response = await got(server.url);
602 console.log(response.body);
603 //=> 'Hello world!'
604
605 await server.close();
606})();
607```
608
609
610## Tips
611
612### User Agent
613
614It's a good idea to set the `'user-agent'` header so the provider can more easily see how their resource is used. By default, it's the URL to this repo.
615
616```js
617const got = require('got');
618const pkg = require('./package.json');
619
620got('sindresorhus.com', {
621 headers: {
622 'user-agent': `my-module/${pkg.version} (https://github.com/username/my-module)`
623 }
624});
625```
626
627### 304 Responses
628
629Bear in mind, if you send an `if-modified-since` header and receive a `304 Not Modified` response, the body will be empty. It's your responsibility to cache and retrieve the body contents.
630
631
632## Related
633
634- [gh-got](https://github.com/sindresorhus/gh-got) - Got convenience wrapper to interact with the GitHub API
635- [gl-got](https://github.com/singapore/gl-got) - Got convenience wrapper to interact with the GitLab API
636- [travis-got](https://github.com/samverschueren/travis-got) - Got convenience wrapper to interact with the Travis API
637- [graphql-got](https://github.com/kevva/graphql-got) - Got convenience wrapper to interact with GraphQL
638- [GotQL](https://github.com/khaosdoctor/gotql) - Got convenience wrapper to interact with GraphQL using JSON-parsed queries instead of strings
639
640
641## Created by
642
643[![Sindre Sorhus](https://github.com/sindresorhus.png?size=100)](https://sindresorhus.com) | [![Vsevolod Strukchinsky](https://github.com/floatdrop.png?size=100)](https://github.com/floatdrop) | [![Alexander Tesfamichael](https://github.com/AlexTes.png?size=100)](https://github.com/AlexTes) | [![Luke Childs](https://github.com/lukechilds.png?size=100)](https://github.com/lukechilds)
644---|---|---|---
645[Sindre Sorhus](https://sindresorhus.com) | [Vsevolod Strukchinsky](https://github.com/floatdrop) | [Alexander Tesfamichael](https://alextes.me) | [Luke Childs](https://github.com/lukechilds)
646
647
648## License
649
650MIT