request

What is request?

The 'request' npm package is a simple, yet powerful HTTP client that supports multiple features such as making HTTP calls, handling responses, streaming data, and more. It is designed to be the simplest way possible to make http calls and supports HTTPS and follows redirects by default.

What are request's main functionalities?

Simple HTTP GET requests

This code performs a simple HTTP GET request to Google's homepage and logs the error, response status code, and the response body.

const request = require('request');
request('http://www.google.com', function (error, response, body) {
  console.log('error:', error);
  console.log('statusCode:', response && response.statusCode);
  console.log('body:', body);
});

Streaming data

This code demonstrates how to stream data from an HTTP request directly to a file, which can be useful for downloading files or handling large amounts of data.

const request = require('request');
const fs = require('fs');
const stream = fs.createWriteStream('file.txt');
request('http://www.google.com').pipe(stream);

Custom HTTP headers

This code shows how to send a custom HTTP header (in this case, the User-Agent header) with a request. This is often required when using certain APIs, like GitHub's.

const request = require('request');
const options = {
  url: 'https://api.github.com/repos/request/request',
  headers: {
    'User-Agent': 'request'
  }
};
function callback(error, response, body) {
  if (!error && response.statusCode == 200) {
    const info = JSON.parse(body);
    console.log(info);
  }
}
request(options, callback);

Handling POST requests

This code snippet demonstrates how to send a POST request with form data, including how to upload a file as part of that form data.

const request = require('request');
const options = {
  method: 'POST',
  url: 'http://service.com/upload',
  headers: {
    'Content-Type': 'multipart/form-data'
  },
  formData: {
    key: 'value',
    file: fs.createReadStream('file.txt')
  }
};
request(options, function (error, response, body) {
  if (error) throw new Error(error);
  console.log(body);
});

Other packages similar to request

axios

Axios is a promise-based HTTP client for the browser and Node.js. It provides a simple API for making HTTP requests and is often used as an alternative to 'request' due to its promise support and interceptors for request/response manipulation.

got

Got is a human-friendly and powerful HTTP request library. It is designed to be a simpler and more performant alternative to 'request', with features like streams support, promise API, and better error handling.

node-fetch

Node-fetch is a light-weight module that brings the Fetch API to Node.js. It is an alternative to 'request' that provides a simpler, promise-based API for making HTTP requests, similar to what is available in modern web browsers.

superagent

Superagent is a small progressive client-side HTTP request library, and Node.js module with the same API, sporting many high-level HTTP client features. It compares to 'request' by offering a fluent API and being lightweight.

README

Request -- Simplified HTTP client

Super simple to use

Request is designed to be the simplest way possible to make http calls. It supports HTTPS and follows redirects by default.

var request = require('request');
request('http://www.google.com', function (error, response, body) {
  if (!error && response.statusCode == 200) {
    console.log(body) // Print the google web page.
  }
})

Streaming

You can stream any response to a file stream.

request('http://google.com/doodle.png').pipe(fs.createWriteStream('doodle.png'))

You can also stream a file to a PUT or POST request. This method will also check the file extension against a mapping of file extensions to content-types (in this case application/json) and use the proper content-type in the PUT request (if the headers don’t already provide one).

fs.createReadStream('file.json').pipe(request.put('http://mysite.com/obj.json'))

Request can also pipe to itself. When doing so, content-type and content-length are preserved in the PUT headers.

request.get('http://google.com/img.png').pipe(request.put('http://mysite.com/img.png'))

Now let’s get fancy.

http.createServer(function (req, resp) {
  if (req.url === '/doodle.png') {
    if (req.method === 'PUT') {
      req.pipe(request.put('http://mysite.com/doodle.png'))
    } else if (req.method === 'GET' || req.method === 'HEAD') {
      request.get('http://mysite.com/doodle.png').pipe(resp)
    }
  }
})

You can also pipe() from http.ServerRequest instances, as well as to http.ServerResponse instances. The HTTP method, headers, and entity-body data will be sent. Which means that, if you don't really care about security, you can do:

http.createServer(function (req, resp) {
  if (req.url === '/doodle.png') {
    var x = request('http://mysite.com/doodle.png')
    req.pipe(x)
    x.pipe(resp)
  }
})

And since pipe() returns the destination stream in ≥ Node 0.5.x you can do one line proxying. :)

req.pipe(request('http://mysite.com/doodle.png')).pipe(resp)

Also, none of this new functionality conflicts with requests previous features, it just expands them.

var r = request.defaults({'proxy':'http://localproxy.com'})

http.createServer(function (req, resp) {
  if (req.url === '/doodle.png') {
    r.get('http://google.com/doodle.png').pipe(resp)
  }
})

You can still use intermediate proxies, the requests will still follow HTTP forwards, etc.

Forms

request supports application/x-www-form-urlencoded and multipart/form-data form uploads. For multipart/related refer to the multipart API.

URL-encoded forms are simple.

request.post('http://service.com/upload', {form:{key:'value'}})
// or
request.post('http://service.com/upload').form({key:'value'})

For multipart/form-data we use the form-data library by @felixge. You don’t need to worry about piping the form object or setting the headers, request will handle that for you.

var r = request.post('http://service.com/upload')
var form = r.form()
form.append('my_field', 'my_value')
form.append('my_buffer', new Buffer([1, 2, 3]))
form.append('my_file', fs.createReadStream(path.join(__dirname, 'doodle.png'))
form.append('remote_file', request('http://google.com/doodle.png'))

HTTP Authentication

request.get('http://some.server.com/').auth('username', 'password', false);
// or
request.get('http://some.server.com/', {
  'auth': {
    'user': 'username',
    'pass': 'password',
    'sendImmediately': false
  }
});

If passed as an option, auth should be a hash containing values user || username, password || pass, and sendImmediately (optional). The method form takes parameters auth(username, password, sendImmediately).

sendImmediately defaults to true, which causes a basic authentication header to be sent. If sendImmediately is false, then request will retry with a proper authentication header after receiving a 401 response from the server (which must contain a WWW-Authenticate header indicating the required authentication method).

Digest authentication is supported, but it only works with sendImmediately set to false; otherwise request will send basic authentication on the initial request, which will probably cause the request to fail.

OAuth Signing

// Twitter OAuth
var qs = require('querystring')
  , oauth =
    { callback: 'http://mysite.com/callback/'
    , consumer_key: CONSUMER_KEY
    , consumer_secret: CONSUMER_SECRET
    }
  , url = 'https://api.twitter.com/oauth/request_token'
  ;
request.post({url:url, oauth:oauth}, function (e, r, body) {
  // Ideally, you would take the body in the response
  // and construct a URL that a user clicks on (like a sign in button).
  // The verifier is only available in the response after a user has
  // verified with twitter that they are authorizing your app.
  var access_token = qs.parse(body)
    , oauth =
      { consumer_key: CONSUMER_KEY
      , consumer_secret: CONSUMER_SECRET
      , token: access_token.oauth_token
      , verifier: access_token.oauth_verifier
      }
    , url = 'https://api.twitter.com/oauth/access_token'
    ;
  request.post({url:url, oauth:oauth}, function (e, r, body) {
    var perm_token = qs.parse(body)
      , oauth =
        { consumer_key: CONSUMER_KEY
        , consumer_secret: CONSUMER_SECRET
        , token: perm_token.oauth_token
        , token_secret: perm_token.oauth_token_secret
        }
      , url = 'https://api.twitter.com/1.1/users/show.json?'
      , params =
        { screen_name: perm_token.screen_name
        , user_id: perm_token.user_id
        }
      ;
    url += qs.stringify(params)
    request.get({url:url, oauth:oauth, json:true}, function (e, r, user) {
      console.log(user)
    })
  })
})

Custom HTTP Headers

HTTP Headers, such as User-Agent, can be set in the options object. In the example below, we call the github API to find out the number of stars and forks for the request repository. This requires a custom User-Agent header as well as https.

var request = require('request');

var options = {
	url: 'https://api.github.com/repos/mikeal/request',
	headers: {
		'User-Agent': 'request'
	}
};

function callback(error, response, body) {
	if (!error && response.statusCode == 200) {
		var info = JSON.parse(body);
		console.log(info.stargazers_count + " Stars");
		console.log(info.forks_count + " Forks");
	}
}

request(options, callback);

request(options, callback)

The first argument can be either a url or an options object. The only required option is uri; all others are optional.

• uri || url - fully qualified uri or a parsed url object from url.parse()
• qs - object containing querystring values to be appended to the uri
• method - http method (default: "GET")
• headers - http headers (default: {})
• body - entity body for PATCH, POST and PUT requests. Must be a Buffer or String.
• form - when passed an object, this sets body to a querystring representation of value, and adds Content-type: application/x-www-form-urlencoded; charset=utf-8 header. When passed no options, a FormData instance is returned (and is piped to request).
• auth - A hash containing values user || username, password || pass, and sendImmediately (optional). See documentation above.
• json - sets body but to JSON representation of value and adds Content-type: application/json header. Additionally, parses the response body as JSON.
• multipart - (experimental) array of objects which contains their own headers and body attribute. Sends multipart/related request. See example below.
• followRedirect - follow HTTP 3xx responses as redirects (default: true)
• followAllRedirects - follow non-GET HTTP 3xx responses as redirects (default: false)
• maxRedirects - the maximum number of redirects to follow (default: 10)
• encoding - Encoding to be used on setEncoding of response data. If null, the body is returned as a Buffer.
• pool - A hash object containing the agents for these requests. If omitted, the request will use the global pool (which is set to node's default maxSockets)
• pool.maxSockets - Integer containing the maximum amount of sockets in the pool.
• timeout - Integer containing the number of milliseconds to wait for a request to respond before aborting the request
• proxy - An HTTP proxy to be used. Supports proxy Auth with Basic Auth, identical to support for the url parameter (by embedding the auth info in the uri)
• oauth - Options for OAuth HMAC-SHA1 signing. See documentation above.
• hawk - Options for Hawk signing. The credentials key must contain the necessary signing info, see hawk docs for details.
• strictSSL - If true, requires SSL certificates be valid. Note: to use your own certificate authority, you need to specify an agent that was created with that CA as an option.
• jar - If true, remember cookies for future use (or define your custom cookie jar; see examples section)
• aws - object containing AWS signing information. Should have the properties key, secret. Also requires the property bucket, unless you’re specifying your bucket as part of the path, or the request doesn’t use a bucket (i.e. GET Services)
• httpSignature - Options for the HTTP Signature Scheme using Joyent's library. The keyId and key properties must be specified. See the docs for other options.
• localAddress - Local interface to bind for network connections.

The callback argument gets 3 arguments:

1. An error when applicable (usually from http.ClientRequest object)
2. An http.IncomingMessage object
3. The third is the response body (String or Buffer, or JSON object if the json option is supplied)

Convenience methods

There are also shorthand methods for different HTTP METHODs and some other conveniences.

request.defaults(options)

This method returns a wrapper around the normal request API that defaults to whatever options you pass in to it.

request.put

Same as request(), but defaults to method: "PUT".

request.put(url)

request.patch

Same as request(), but defaults to method: "PATCH".

request.patch(url)

request.post

Same as request(), but defaults to method: "POST".

request.post(url)

request.head

Same as request() but defaults to method: "HEAD".

request.head(url)

request.del

Same as request(), but defaults to method: "DELETE".

request.del(url)

request.get

Same as request() (for uniformity).

request.get(url)

request.cookie

Function that creates a new cookie.

request.cookie('cookie_string_here')

request.jar

Function that creates a new cookie jar.

request.jar()

Examples:

  var request = require('request')
    , rand = Math.floor(Math.random()*100000000).toString()
    ;
  request(
    { method: 'PUT'
    , uri: 'http://mikeal.iriscouch.com/testjs/' + rand
    , multipart:
      [ { 'content-type': 'application/json'
        ,  body: JSON.stringify({foo: 'bar', _attachments: {'message.txt': {follows: true, length: 18, 'content_type': 'text/plain' }}})
        }
      , { body: 'I am an attachment' }
      ]
    }
  , function (error, response, body) {
      if(response.statusCode == 201){
        console.log('document saved as: http://mikeal.iriscouch.com/testjs/'+ rand)
      } else {
        console.log('error: '+ response.statusCode)
        console.log(body)
      }
    }
  )

Cookies are disabled by default (else, they would be used in subsequent requests). To enable cookies, set jar to true (either in defaults or options).

var request = request.defaults({jar: true})
request('http://www.google.com', function () {
  request('http://images.google.com')
})

To use a custom cookie jar (instead request’s global cookie jar), set jar to an instance of request.jar() (either in defaults or options)

var j = request.jar()
var request = request.defaults({jar:j})
request('http://www.google.com', function () {
  request('http://images.google.com')
})

OR

Note that setCookie requires at least three parameters, and the last is required to be a callback.

var j = request.jar()
var cookie = request.cookie('your_cookie_here')
j.setCookie(cookie, uri, function (err, cookie){})
request({url: 'http://www.google.com', jar: j}, function () {
  request('http://images.google.com')
})

Changelog

v2.31.0 (2014/01/08)

• #645 update twitter api url to v1.1 (@mick)
• #746 README: Markdown code highlight (@weakish)
• #745 updating setCookie example to make it clear that the callback is required (@emkay)
• #742 Add note about JSON output body type (@iansltx)
• #741 README example is using old cookie jar api (@emkay)
• #736 Fix callback arguments documentation (@mmalecki)
• #732 JSHINT: Creating global 'for' variable. Should be 'for (var ...'. (@Fritz-Lium)
• #730 better HTTP DIGEST support (@dai-shi)
• #728 Fix TypeError when calling request.cookie (@scarletmeow)
• #727 fix requester bug (@jchris)
• #724 README.md: add custom HTTP Headers example. (@tcort)
• #719 Made a comment gender neutral. (@unsetbit)
• #715 Request.multipart no longer crashes when header 'Content-type' present (@pastaclub)
• #710 Fixing listing in callback part of docs. (@lukasz-zak)
• #696 Edited README.md for formatting and clarity of phrasing (@Zearin)
• #694 Typo in README (@VRMink)
• #690 Handle blank password in basic auth. (@diversario)
• #682 Optional dependencies (@Turbo87)
• #683 Travis CI support (@Turbo87)
• #674 change cookie module,to tough-cookie.please check it . (@sxyizhiren)
• #666 make ciphers and secureProtocol to work in https request (@richarddong)
• #656 Test case for #304. (@diversario)
• #662 option.tunnel to explicitly disable tunneling (@seanmonstar)
• #659 fix failure when running with NODE_DEBUG=request, and a test for that (@jrgm)
• #630 Send random cnonce for HTTP Digest requests (@wprl)
• #619 decouple things a bit (@joaojeronimo)
• #613 Fixes #583, moved initialization of self.uri.pathname (@lexander)
• #605 Only include ":" + pass in Basic Auth if it's defined (fixes #602) (@bendrucker)
• #596 Global agent is being used when pool is specified (@Cauldrath)
• #594 Emit complete event when there is no callback (@RomainLK)
• #601 Fixed a small typo (@michalstanko)
• #589 Prevent setting headers after they are sent (@geek)
• #587 Global cookie jar disabled by default (@threepointone)
• #544 Update http-signature version. (@davidlehn)
• #581 Fix spelling of "ignoring." (@bigeasy)
• #568 use agentOptions to create agent when specified in request (@SamPlacette)
• #564 Fix redirections (@criloz)
• #541 The exported request function doesn't have an auth method (@tschaub)
• #542 Expose Request class (@regality)
• #536 Allow explicitly empty user field for basic authentication. (@mikeando)
• #532 fix typo (@fredericosilva)
• #497 Added redirect event (@Cauldrath)
• #503 Fix basic auth for passwords that contain colons (@tonistiigi)
• #521 Improving test-localAddress.js (@noway)
• #529 dependencies versions bump (@jodaka)
• #523 Updating dependencies (@noway)
• #520 Fixing test-tunnel.js (@noway)
• #519 Update internal path state on post-creation QS changes (@jblebrun)
• #510 Add HTTP Signature support. (@davidlehn)
• #502 Fix POST (and probably other) requests that are retried after 401 Unauthorized (@nylen)
• #508 Honor the .strictSSL option when using proxies (tunnel-agent) (@jhs)
• #512 Make password optional to support the format: http://username@hostname/ (@pajato1)
• #513 add 'localAddress' support (@yyfrankyy)
• #498 Moving response emit above setHeaders on destination streams (@kenperkins)
• #490 Empty response body (3-rd argument) must be passed to callback as an empty string (@Olegas)
• #479 Changing so if Accept header is explicitly set, sending json does not ov... (@RoryH)
• #475 Use unescape from querystring (@shimaore)
• #473 V0.10 compat (@isaacs)
• #471 Using querystring library from visionmedia (@kbackowski)
• #461 Strip the UTF8 BOM from a UTF encoded response (@kppullin)
• #460 hawk 0.10.0 (@hueniverse)
• #462 if query params are empty, then request path shouldn't end with a '?' (merges cleanly now) (@jaipandya)
• #456 hawk 0.9.0 (@hueniverse)
• #429 Copy options before adding callback. (@nrn, @nfriedly, @youurayy, @jplock, @kapetan, @landeiro, @othiym23, @mmalecki)
• #454 Destroy the response if present when destroying the request (clean merge) (@mafintosh)
• #310 Twitter Oauth Stuff Out of Date; Now Updated (@joemccann, @isaacs, @mscdex)
• #413 rename googledoodle.png to .jpg (@nfriedly, @youurayy, @jplock, @kapetan, @landeiro, @othiym23, @mmalecki)
• #448 Convenience method for PATCH (@mloar)
• #444 protect against double callbacks on error path (@spollack)
• #433 Added support for HTTPS cert & key (@mmalecki)
• #430 Respect specified {Host,host} headers, not just {host} (@andrewschaaf)
• #415 Fixed a typo. (@jerem)
• #338 Add more auth options, including digest support (@nylen)
• #403 Optimize environment lookup to happen once only (@mmalecki)
• #398 Add more reporting to tests (@mmalecki)
• #388 Ensure "safe" toJSON doesn't break EventEmitters (@othiym23)
• #381 Resolving "Invalid signature. Expected signature base string: " (@landeiro)
• #380 Fixes missing host header on retried request when using forever agent (@mac-)
• #376 Headers lost on redirect (@kapetan)
• #375 Fix for missing oauth_timestamp parameter (@jplock)
• #374 Correct Host header for proxy tunnel CONNECT (@youurayy)
• #370 Twitter reverse auth uses x_auth_mode not x_auth_type (@drudge)
• #369 Don't remove x_auth_mode for Twitter reverse auth (@drudge)
• #344 Make AWS auth signing find headers correctly (@nlf)
• #363 rfc3986 on base_uri, now passes tests (@jeffmarshall)
• #362 Running rfc3986 on base_uri in oauth.hmacsign instead of just encodeURIComponent (@jeffmarshall)
• #361 Don't create a Content-Length header if we already have it set (@danjenkins)
• #360 Delete self._form along with everything else on redirect (@jgautier)
• #355 stop sending erroneous headers on redirected requests (@azylman)
• #332 Fix #296 - Only set Content-Type if body exists (@Marsup)
• #343 Allow AWS to work in more situations, added a note in the README on its usage (@nlf)
• #320 request.defaults() doesn't need to wrap jar() (@StuartHarris)
• #322 Fix + test for piped into request bumped into redirect. #321 (@alexindigo)
• #326 Do not try to remove listener from an undefined connection (@CartoDB)
• #318 Pass servername to tunneling secure socket creation (@isaacs)
• #317 Workaround for #313 (@isaacs)
• #293 Allow parser errors to bubble up to request (@mscdex)
• #290 A test for #289 (@isaacs)
• #280 Like in node.js print options if NODE_DEBUG contains the word request (@Filirom1)
• #207 Fix #206 Change HTTP/HTTPS agent when redirecting between protocols (@isaacs)
• #214 documenting additional behavior of json option (@jphaas, @vpulim)
• #272 Boundary begins with CRLF? (@elspoono, @timshadel, @naholyr, @nanodocumet, @TehShrike)
• #284 Remove stray console.log() call in multipart generator. (@bcherry)
• #241 Composability updates suggested by issue #239 (@polotek)
• #282 OAuth Authorization header contains non-"oauth_" parameters (@jplock)
• #279 fix tests with boundary by injecting boundry from header (@benatkin)
• #273 Pipe back pressure issue (@mafintosh)
• #268 I'm not OCD seriously (@TehShrike)
• #263 Bug in OAuth key generation for sha1 (@nanodocumet)
• #265 uncaughtException when redirected to invalid URI (@naholyr)
• #262 JSON test should check for equality (@timshadel)
• #261 Setting 'pool' to 'false' does NOT disable Agent pooling (@timshadel)
• #249 Fix for the fix of your (closed) issue #89 where self.headers[content-length] is set to 0 for all methods (@sethbridges, @polotek, @zephrax, @jeromegn)
• #255 multipart allow body === '' ( the empty string ) (@Filirom1)
• #260 fixed just another leak of 'i' (@sreuter)
• #246 Fixing the set-cookie header (@jeromegn)
• #243 Dynamic boundary (@zephrax)
• #240 don't error when null is passed for options (@polotek)
• #211 Replace all occurrences of special chars in RFC3986 (@chriso, @vpulim)
• #224 Multipart content-type change (@janjongboom)
• #217 need to use Authorization (titlecase) header with Tumblr OAuth (@visnup)
• #203 Fix cookie and redirect bugs and add auth support for HTTPS tunnel (@vpulim)
• #199 Tunnel (@isaacs)
• #198 Bugfix on forever usage of util.inherits (@isaacs)
• #197 Make ForeverAgent work with HTTPS (@isaacs)
• #193 Fixes GH-119 (@goatslacker)
• #188 Add abort support to the returned request (@itay)
• #176 Querystring option (@csainty)
• #182 Fix request.defaults to support (uri, options, callback) api (@twilson63)
• #180 Modified the post, put, head and del shortcuts to support uri optional param (@twilson63)
• #179 fix to add opts in .pipe(stream, opts) (@substack)
• #177 Issue #173 Support uri as first and optional config as second argument (@twilson63)
• #170 can't create a cookie in a wrapped request (defaults) (@fabianonunes)
• #168 Picking off an EasyFix by adding some missing mimetypes. (@serby)
• #161 Fix cookie jar/headers.cookie collision (#125) (@papandreou)
• #162 Fix issue #159 (@dpetukhov)
• #90 add option followAllRedirects to follow post/put redirects (@jroes)
• #148 Retry Agent (@thejh)
• #146 Multipart should respect content-type if previously set (@apeace)
• #144 added "form" option to readme (@petejkim)
• #133 Fixed cookies parsing (@afanasy)
• #135 host vs hostname (@iangreenleaf)
• #132 return the body as a Buffer when encoding is set to null (@jahewson)
• #112 Support using a custom http-like module (@jhs)
• #104 Cookie handling contains bugs (@janjongboom)
• #121 Another patch for cookie handling regression (@jhurliman)
• #117 Remove the global i (@3rd-Eden)
• #110 Update to Iris Couch URL (@jhs)
• #86 Can't post binary to multipart requests (@kkaefer)
• #105 added test for proxy option. (@dominictarr)
• #102 Implemented cookies - closes issue 82: https://github.com/mikeal/request/issues/82 (@alessioalex)
• #97 Typo in previous pull causes TypeError in non-0.5.11 versions (@isaacs)
• #96 Authless parsed url host support (@isaacs)
• #81 Enhance redirect handling (@danmactough)
• #78 Don't try to do strictSSL for non-ssl connections (@isaacs)
• #76 Bug when a request fails and a timeout is set (@Marsup)
• #70 add test script to package.json (@isaacs, @aheckmann)
• #73 Fix #71 Respect the strictSSL flag (@isaacs)
• #69 Flatten chunked requests properly (@isaacs)
• #67 fixed global variable leaks (@aheckmann)
• #66 Do not overwrite established content-type headers for read stream deliver (@voodootikigod)
• #53 Parse json: Issue #51 (@benatkin)
• #45 Added timeout option (@mbrevoort)
• #35 The "end" event isn't emitted for some responses (@voxpelli)
• #31 Error on piping a request to a destination (@tobowers)