What is got?
The 'got' npm package is a human-friendly and powerful HTTP request library for Node.js. It provides an easy-to-use API for making HTTP requests and supports many features like streams, pagination, JSON parsing, and more.
What are got's main functionalities?
Simplified HTTP requests
This feature allows you to perform HTTP GET requests with a promise-based API. The example shows how to fetch a webpage and log the HTML content.
const got = require('got');
got('https://sindresorhus.com').then(response => {
console.log(response.body);
}).catch(error => {
console.log(error.response.body);
});
JSON support
This feature automatically parses JSON responses. The example demonstrates fetching JSON data from an API and logging the parsed object.
const got = require('got');
got('https://api.example.com/data', { responseType: 'json' }).then(response => {
console.log(response.body);
}).catch(error => {
console.log(error.response.body);
});
POST requests
This feature allows you to send POST requests with JSON bodies. The example shows how to send a POST request with a JSON payload and receive a JSON response.
const got = require('got');
got.post('https://api.example.com/submit', {
json: {
key: 'value'
},
responseType: 'json'
}).then(response => {
console.log(response.body);
}).catch(error => {
console.log(error.response.body);
});
Error handling
This feature provides comprehensive error handling for various types of request failures. The example demonstrates how to handle different error scenarios when a request fails.
const got = require('got');
got('https://api.example.com/wrong-endpoint').then(response => {
console.log(response.body);
}).catch(error => {
if (error.response) {
console.log('The server responded with a non-2xx status code.');
} else if (error.request) {
console.log('The request was made but no response was received');
} else {
console.log('An error occurred when trying to perform the request.');
}
});
Stream support
This feature allows you to use got as a stream. The example shows how to stream a webpage's content and write it to a file.
const got = require('got');
const fs = require('fs');
const stream = got.stream('https://sindresorhus.com');
stream.pipe(fs.createWriteStream('index.html'));
Other packages similar to got
axios
Axios is a promise-based HTTP client for the browser and Node.js. It provides an API similar to got but also works in the browser. Axios has interceptors that allow you to transform requests and responses before they are handled by then or catch.
request
Request is a simplified HTTP request client that was very popular but is now deprecated. It had a callback-based API but also supported promises. Got is considered a modern alternative to Request with promise support by default.
node-fetch
Node-fetch is a light-weight module that brings the Fetch API to Node.js. It is a minimalistic and straightforward API that resembles the Fetch API provided by modern browsers, making it familiar to front-end developers.
superagent
Superagent is a small progressive client-side HTTP request library. It has a fluent API that allows chaining methods to configure requests, and it can be used on both server and client side. Compared to got, it has a more object-oriented style.
Simplified HTTP/HTTPS requests
A nicer interface to the built-in http
module.
It supports following redirects, streams, automagically handling gzip/deflate and some convenience options.
Created because request
is bloated (several megabytes!) and slow.
Install
$ npm install --save got
Usage
var got = require('got');
got('todomvc.com', function (err, data, res) {
console.log(data);
});
got('todomvc.com').pipe(fs.createWriteStream('index.html'));
fs.createReadStream('index.html').pipe(got.post('todomvc.com'));
API
It's a GET
request by default, but can be changed in options
.
got(url, [options], [callback])
url
Required
Type: string
, object
The URL to request or bare http.request options object.
Properties from options
will override properties in the parsed url
.
options
Type: object
Any of the http.request
options.
body
Type: string
, Buffer
, ReadableStream
This option and stream mode are mutually exclusive.
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.
encoding
Type: string
, null
Default: 'utf8'
Encoding to be used on setEncoding
of the response data. If null
, the body is returned as a Buffer.
json
Type: boolean
Default: false
This option and stream mode are mutually exclusive.
Parse response body with JSON.parse
and set accept
header to application/json
.
query
Type: string
, object
Query string object that will be added to the request URL. This will override the query string in url
.
timeout
Type: number
Milliseconds after which the request will be aborted and an error event with ETIMEDOUT
code will be emitted.
agent
http.Agent instance.
If undefined
- infinity-agent
will be used to backport Agent class from Node.js core.
To use default globalAgent just pass null
.
callback(error, data, response)
error
Error
object with HTTP status code as code
property.
data
The data you requested.
response
The response object.
When in stream mode, you can listen for events:
.on('response', response)
response
event to get the response object of the final request.
.on('redirect', response, nextOptions)
redirect
event to get the response object of a redirect. Second argument is options for the next request to the redirect location.
.on('error', error, body, response)
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.
response
The response object.
got.get(url, [options], [callback])
got.post(url, [options], [callback])
got.put(url, [options], [callback])
got.patch(url, [options], [callback])
got.head(url, [options], [callback])
got.delete(url, [options], [callback])
Sets options.method
to the method name and makes a request.
Proxy
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 () {});
Tip
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 () {});
Related
- gh-got - Convenience wrapper for interacting with the GitHub API
- got-promise - Promise wrapper
Created by
License
MIT © Sindre Sorhus