Simplified HTTP/HTTPS requests
A nicer interface to the built-in http
module.
It supports following redirects, promises, streams, automagically handling gzip/deflate and some convenience options.
Created because request
is bloated (several megabytes!).
$ npm install --save got
var got = require('got');
// Callback mode
got('todomvc.com', function (err, data, res) {
console.log(data);
//=> '<!doctype html> ...'
});
// Promise mode
got('todomvc.com')
.then(function (res) {
console.log(res.body);
})
.catch(function (err) {
console.error(err);
console.error(err.response && err.response.body);
});
// Stream mode
got.stream('todomvc.com').pipe(fs.createWriteStream('index.html'));
// For POST, PUT and PATCH methods got.stream returns a WritableStream
fs.createReadStream('index.html').pipe(got.stream.post('todomvc.com'));
It's a GET
request by default, but can be changed in options
.
Required
Type: string
, object
The URL to request or a http.request
options object.
Properties from options
will override properties in the parsed url
.
Type: object
Any of the http.request
options.
Type: string
, Buffer
, ReadableStream
, Object
This is mutually exclusive with stream mode.
Body that will be sent with a POST
request.
If present in options
and options.method
is not set, options.method
will be set to POST
.
If 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.
If body
is a plain Object, it will be stringified with querystring.stringify
and sent as application/x-www-form-urlencoded
.
Type: string
, null
Default: 'utf8'
Encoding to be used on setEncoding
of the response data. If null
, the body is returned as a Buffer.
Type: boolean
Default: false
This is mutually exclusive with stream mode.
Parse response body with JSON.parse
and set accept
header to application/json
.
Type: string
, object
Query string object that will be added to the request URL. This will override the query string in url
.
Type: number
Milliseconds after which the request will be aborted and an error event with ETIMEDOUT
code will be emitted.
Function to be called, when error or data received. If omitted, a promise will be returned.
Error
object with HTTP status code as statusCode
property.
The data you requested.
The response object.
When in stream mode, you can listen for events:
request
event to get the request object of the request.
response
event to get the response object of the final request.
redirect
event to get the response object of a redirect. Second argument is options for the next request to the redirect location.
error
event emitted in case of protocol error (like ENOTFOUND
etc.) or status error (4xx or 5xx). Second argument is body of server response in case of status error. Third argument is response object.
Sets options.method
to the method name and makes a request.
Each error contains (if available) host
, hostname
, method
and path
properties to make debug easier.
When a request fails. Contains a code
property with error class code, like ECONNREFUSED
.
When reading from response stream fails.
When json
option is enabled and JSON.parse
fails.
When server response code is not 2xx. Contains statusCode
and statusMessage
.
When server redirects you more than 10 times.
You can use the tunnel
module with the agent
option to work with proxies:
var got = require('got');
var tunnel = require('tunnel');
got('todomvc.com', {
agent: tunnel.httpOverHttp({
proxy: {
host: 'localhost'
}
})
}, function () {});
It'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.
var got = require('got');
got('todomvc.com', {
headers: {
'user-agent': 'https://github.com/your-username/repo-name'
}
}, function () {});
It is a known issue with old good Node 0.10.x http.Agent
and agent.maxSockets
, which is set to 5
. This can cause low performance and in rare cases deadlocks. To avoid this you can set it manually:
require('http').globalAgent.maxSockets = Infinity;
require('https').globalAgent.maxSockets = Infinity;
This should only ever be done if you have Node version 0.10.x and at the top-level app layer.
- gh-got - Convenience wrapper for interacting with the GitHub API
Sindre Sorhus | Vsevolod Strukchinsky |
MIT © Sindre Sorhus