Unirest is a set of lightweight HTTP libraries available in multiple languages, built and maintained by Kong, who also maintain the open-source API Gateway Kong.
To utilize unirest for node.js install the the npm module:
$ npm install unirestAfter installing the npm package you can now start simplifying requests like so:
var unirest = require('unirest');You're probably wondering how by using Unirest makes creating requests easier. Besides automatically supporting gzip, and parsing responses, lets start with a basic working example:
unirest
.post('http://mockbin.com/request')
.headers({'Accept': 'application/json', 'Content-Type': 'application/json'})
.send({ "parameter": 23, "foo": "bar" })
.then((response) => {
console.log(response.body)
})Transferring file data has been simplified:
unirest
.post('http://mockbin.com/request')
.headers({'Content-Type': 'multipart/form-data'})
.field('parameter', 'value') // Form field
.attach('file', '/tmp/file') // Attachment
.then(function (response) {
console.log(response.body)
})unirest
.post('http://mockbin.com/request')
.headers({'Accept': 'application/json'})
.send(Buffer.from([1,2,3]))
.then(function (response) {
console.log(response.body)
})A request can be initiated by invoking the appropriate method on the unirest object, then calling .end() to send the request. Alternatively you can send the request directly by providing a callback along with the url.
method- Request type (GET, PUT, POST, etc...)uri- Optional; When passed will return a Request object. Otherwise returns generated function withmethodpre-defined (e.g.unirest.get)headers(Object) - Optional; HTTP Request headersbody(Mixed) - Optional; HTTP Request bodycallback(Function) - Optional; Invoked when Request has finalized with the argument Response
method- Request type, pre-defined methods, see below.url- Request location.headers(Object|Function) - Optional; WhenObjectheaders are passed along to theRequest.headermethod, whenFunctionthis argument is used as thecallback.body(Mixed|Function) - Optional; Whenbodyis not aFunctionit will be passed along toRequest.send()method, otherwise when aFunctionit will be used as thecallback.callback(Function) - Optional; Calls end with given argument, otherwiseRequestis returned.
All arguments above, with the exclusion of url, will accept a Function as the callback.
When no callback is present, the Request object will be returned.
Returns a Request object with the method option set to GET
var Request = unirest.get('http://mockbin.com/request')Returns a Request object with the method option set to HEAD
let Request = unirest.head('http://mockbin.com/request')Returns a Request object with the method option set to PUT
let Request = unirest.put('http://mockbin.com/request')Returns a Request object with the method option set to POST
let Request = unirest.post('http://mockbin.com/request')Returns a Request object with the method option set to PATCH
let Request = unirest.patch('http://mockbin.com/request')Returns a Request object with the method option set to DELETE
let Request = unirest.delete('http://mockbin.com/request')Creates a container to store multiple cookies, i.e. a cookie jar.
let CookieJar = unirest.jar()
CookieJar.add('key=value', '/')
unirest
.get('http://mockbin.com/request')
.jar(CookieJar)Creates a cookie, see above for example.
mikeal/request library (the underlying layer of unirest) for direct use.
Provides simple and easy to use methods for manipulating the request prior to being sent. This object is created when a Unirest Method is invoked. This object contains methods that are chainable like other libraries such as jQuery and popular request module Superagent (which this library is modeled after slightly).
Example
var Request = unirest.post('http://mockbin.com/request');
Request
.header('Accept', 'application/json')
.end(function (response) {
...
})Request Methods differ from Option Methods (See Below) in that these methods transform, or handle the data in a sugared way, where as Option Methods require a more hands on approach.
Accepts either an Object containing user, pass, and optionally sendImmediately.
user(String) - Authentication Usernamepass(String) - Authentication PasswordsendImmediately(String) - Optional; Defaults totrue; Flag to determine whether Request should send the basic authentication header along with the request. Upon being false, Request will retry with a proper authentication header after receiving a401response from the server (which must contain aWWW-Authenticateheader indicating the required authentication method)
Object
Request.auth({
user: 'Nijiko',
pass: 'insecure',
sendImmediately: true
})Arguments
Request.auth('Nijiko', 'insecure', true)Suggested Method for setting Headers
Accepts either an Object containing header-name: value entries,
or field and value arguments. Each entry is then stored in a two locations, one in the case-sensitive Request.options.headers and the other on a private _headers object that is case-insensitive for internal header lookup.
field(String) - Header name, such asAcceptsvalue(String) - Header value, such asapplication/json
Object
Request.headers({
'Accept': 'application/json',
'User-Agent': 'Unirest Node.js'
})Note the usage of Request.headers which is simply an alias to the Request.header method, you can also use Request.set to set headers.
Arguments
Request.header('Accept', 'application/json');Experimental
Similiar to Request.multipart() except it only allows one object to be passed at a time and does the pre-processing on necessary body values for you.
Each object is then appended to the Request.options.multipart array.
Request
.part({
'content-type': 'application/json',
body: { foo: 'bar' }
})
.part({
'content-type': 'text/html',
body: '<strong>Hello World!</strong>'
})Serializes argument passed to a querystring representation.
Should url already contain a querystring, the representation will be appended to the url.
unirest
.post('http://mockbin.com/request')
.query('name=nijiko')
.query({
pet: 'spot'
})
.then((response) => {
console.log(response.body)
})Data marshalling for HTTP request body data
Determines whether data mime-type is form or json.
For irregular mime-types the .type() method is used to infer the content-type header.
When mime-type is application/x-www-form-urlencoded data is appended rather than overwritten.
JSON
unirest
.post('http://mockbin.com/request')
.type('json')
.send({
foo: 'bar',
hello: 3
})
.then((response) => {
console.log(response.body)
})FORM Encoded
// Body would be:
// name=nijiko&pet=turtle
unirest
.post('http://mockbin.com/request')
.send('name=nijiko')
.send('pet=spot')
.then((response) => {
console.log(response.body)
})HTML / Other
unirest
.post('http://mockbin.com/request')
.set('Content-Type', 'text/html')
.send('<strong>Hello World!</strong>')
.then((response) => {
console.log(response.body)
})Sets the header Content-Type through either lookup for extensions (xml, png, json, etc...) using mime or using the full value such as application/json.
Uses Request.header to set header value.
Request.type('application/json') // Content-Type: application/json
Request.type('json') // Content-Type: application/json
Request.type('html') // Content-Type: text/html
…The following methods are sugar methods for attaching files, and form fields. Instead of handling files and processing them yourself Unirest can do that for you.
Object should consist of name: 'path' otherwise use name and path.
name(String) - File field namepath(String|Object) - File value, AStringwill be parsed based on its value. IfpathcontainshttporhttpsRequest will handle it as aremote file. Ifpathdoes not containhttporhttpsthen unirest will assume that it is the path to a local file and attempt to find it usingpath.resolve. AnObjectis directly set, so you can do pre-processing if you want without worrying about the string value.
Object
unirest
.post('http://mockbin.com/request')
.header('Accept', 'application/json')
.field({
'parameter': 'value'
})
.attach({
'file': 'dog.png',
'relative file': fs.createReadStream(path.join(__dirname, 'dog.png')),
'remote file': unirest.request('http://google.com/doodle.png')
})
.then((response) => {
console.log(response.body)
})Arguments
unirest
.post('http://mockbin.com/request')
.header('Accept', 'application/json')
.field('parameter', 'value') // Form field
.attach('file', 'dog.png') // Attachment
.attach('remote file', fs.createReadStream(path.join(__dirname, 'dog.png'))) // Same as above.
.attach('remote file', unirest.request('http://google.com/doodle.png'))
.then((response) => {
console.log(response.body)
})Object should consist of name: 'value' otherwise use name and value
See Request.attach for usage.
Sets _stream flag to use request streaming instead of direct form-data usage.
This seemingly appears to only work for node servers, use streaming only if you are a hundred percent sure it will work.
Tread carefully.
The options object is where almost all of the request settings live. Each option method sugars to a field on this object to allow for chaining and ease of use. If
you have trouble with an option method and wish to directly access the options object
you are free to do so.
This object is modeled after the request libraries options that are passed along through its constructor.
url(String|Object) - Url, or object parsed fromurl.parse()qs(Object) - Object consisting ofquerystringvalues to append tourlupon request.method(String) - DefaultGET; HTTP Method.headers(Object) - Default{}; HTTP Headers.body(String|Object) - Entity body for certain requests.form(Object) - Form data.auth(Object) - SeeRequest.auth()below.multipart(Object) - Experimental; See documentation below.followRedirect(Boolean) - Defaulttrue; Follow HTTP3xxresponses as redirects.followAllRedirects(Boolean) - Defaultfalse; Follow Non-GET HTTP3xxresponses as redirects.maxRedirects(Number) - Default10; Maximum number of redirects before aborting.encoding(String) - Encoding to be used onsetEncodingof response data.timeout(Number) - Number of milliseconds to wait before aborting.proxy(String) - SeeRequest.proxy()below.oauth(Object) - SeeRequest.oauth()below.hawk(Object) - SeeRequest.hawk()belowstrictSSL(Boolean) - Defaulttrue; SeeRequest.strictSSL()below.secureProtocol(String) - SeeRequest.secureProtocol()below.jar(Boolean|Jar) - SeeRequest.jar()below.aws(Object) - SeeRequest.aws()below.httpSignature(Object) - SeeRequest.httpSignature()Below.localAddress(String) - SeeRequest.localAddress()Below.pool(Object) - SeeRequest.pool()Below.forever(Boolean) - Defaultundefined; SeeRequest.forever()Below
Sets url location of the current request on Request.options to the given String
Request.url('http://mockbin.com/request');Sets method value on Request.options to the given value.
Request.method('HEAD');Sets form object on Request.options to the given object.
When used body is set to the object passed as a querystring representation and the Content-Type header to application/x-www-form-urlencoded; charset=utf-8
Request.form({
key: 'value'
})Experimental
Sets multipart array containing multipart-form objects on Request.options to be sent along with the Request.
Each objects property with the exclusion of body is treated as a header value. Each body value must be pre-processed if necessary when using this method.
Request.multipart([{
'content-type': 'application/json',
body: JSON.stringify({
foo: 'bar'
})
}, {
'content-type': 'text/html',
body: '<strong>Hello World!</strong>'
}])Sets maxRedirects, the number of redirects the current Request will follow, on Request.options based on the given value.
Request.maxRedirects(6)Sets followRedirect flag on Request.options for whether the current Request should follow HTTP redirects based on the given value.
Request.followRedirect(true);Sets timeout, number of milliseconds Request should wait for a response before aborting, on Request.options based on the given value.
Request.timeout(2000)Sets encoding, encoding to be used on setEncoding of response data if set to null, the body is returned as a Buffer, on Request.options based on given value.
Request.encoding('utf-8')Sets strictSSL flag to require that SSL certificates be valid on Request.options based on given value.
Request.strictSSL(true)Sets httpSignature
Sets proxy, HTTP Proxy to be set on Request.options based on value.
Request.proxy('http://localproxy.com')Sets the secure protocol to use:
Request.secureProtocol('SSLv2_method')
// or
Request.secureProtocol('SSLv3_client_method')See openssl.org for all possible values.
Sets aws, AWS Signing Credentials, on Request.options
Request.aws({
key: 'AWS_S3_KEY',
secret: 'AWS_S3_SECRET',
bucket: 'BUCKET NAME'
})Sets oauth, list of oauth credentials, on Request.options based on given object.
unirest
.get('https://api.twitter.com/oauth/request_token')
.oauth({
callback: 'http://mysite.com/callback/',
consumer_key: 'CONSUMER_KEY',
consumer_secret: 'CONSUMER_SECRET'
})
.then(response => {
let access_token = response.body
return unirest
.post('https://api.twitter.com/oauth/access_token')
.oauth({
consumer_key: 'CONSUMER_KEY',
consumer_secret: 'CONSUMER_SECRET',
token: access_token.oauth_token,
verifier: token: access_token.oauth_verifier
})
})
.then((response) => {
var token = response.body
return unirest
.get('https://api.twitter.com/1/users/show.json')
.oauth({
consumer_key: 'CONSUMER_KEY',
consumer_secret: 'CONSUMER_SECRET',
token: token.oauth_token,
token_secret: token.oauth_token_secret
})
.query({
screen_name: token.screen_name,
user_id: token.user_id
})
})
.then((response) => {
console.log(response.body)
})Sets hawk object on Request.options to the given object.
Hawk requires a field credentials as seen in their documentation, and below.
Request.hawk({
credentials: {
key: 'werxhqb98rpaxn39848xrunpaw3489ruxnpa98w4rxn',
algorithm: 'sha256',
user: 'Steve'
}
})Sets localAddress, local interface to bind for network connections, on Request.options
Request.localAddress('127.0.0.1')
Request.localAddress('1.2.3.4')Sets jar, cookie container, on Request.options. When set to true it stores cookies for future usage.
See unirest.jar for more information on how to use Jar argument.
Sets pool object on Request.options to the given object.
A maxSockets property can also be provided on the pool object to set the max number of sockets for all agents created.
Note that if you are sending multiple requests in a loop and creating multiple new pool objects, maxSockets will not work as intended. To work around this, create the pool object with the maxSockets property outside of the loop.
poolOption = { maxSockets: 100 }
Request.pool poolOptionSets forever flag to use forever-agent module. When set to true, default http agent will be replaced by forever-agent, which keeps socket connections alive between keep-alive requests.
Request.forever(true);Promise polyfill method. Wraps Request.end in a Promise and will resolve or
reject based on the result of the request.
unirest
.get('http://mockbin.com/request')
.then((response) => {
console.log(response)
})
.catch(err => {
console.log(err)
})Sends HTTP Request and awaits Response finalization. Request compression and Response decompression occurs here.
Upon HTTP Response post-processing occurs and invokes callback with a single argument, the [Response](#response) object.
unirest
.get('http://mockbin.com/request')
.end((response) => {
console.log(response)
})Alias for Request.header()
Alias for Request.header()
Alias for Request.maxRedirects()
Alias for Request.followRedirect()
Alias for Request.strictSSL()
Alias for Request.localAddress()
Alias for Request.end()
Alias for Request.end()
Alias for Request.end()
Alias for Request.end()
Upon ending a request, and receiving a Response the object that is returned contains a number of helpful properties to ease coding pains.
body(Mixed) - Processed body dataraw_body(Mixed) - Unprocessed body dataheaders(Object) - Header detailscookies(Object) - Cookies fromset-cookies, andcookieheaders.httpVersion(String) - Server http version. (e.g. 1.1)httpVersionMajor(Number) - Major number (e.g. 1)httpVersionMinor(Number) - Minor number (e.g. 1)url(String) - Dependant on input, can be empty.domain(String|null) - Dependant on input, can be empty.method(String|null) - Method used, dependant on input.client(Object) - Client Object. Detailed information regarding the Connection and Byte throughput.connection(Object) - Client Object. Specific connection object, useful for events such as errors. Advancedsocket(Object) Client Object. Socket specific object and information. Most throughput is same across all three client objects.request(Object) - Initial request object.setEncoding(Function) - Set encoding type.
code(Number) - Status Code, i.e.200status(Number) - Status Code, same as above.statusType(Number) - Status Code Range Type1- Info2- Ok3- Miscellaneous4- Client Error5- Server Error
info(Boolean) - Status Range Info?ok(Boolean) - Status Range Ok?clientError(Boolean) - Status Range Client Error?serverError(Boolean) - Status Range Server Error?accepted(Boolean) - Status Code202?noContent(Boolean) - Status Code204or1223?badRequest(Boolean) - Status Code400?unauthorized(Boolean) - Status Code401?notAcceptable(Boolean) - Status Code406?notFound(Boolean) - Status Code404?forbidden(Boolean) - Status Code403?error(Boolean|Object) - Dependant on status code range.
Sugar method for retrieving a cookie from the response.cookies object.
var CookieJar = unirest.jar();
CookieJar.add(unirest.cookie('another cookie=23'));
unirest.get('http://google.com').jar(CookieJar).end(function (response) {
// Except google trims the value passed :/
console.log(response.cookie('another cookie'));
});- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create new Pull Request
Made with ♥ from the Kong team
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent
