µRequest - Minimalist HTTP client

A lightweight alternative to (and drop-in replacement for) request.

Written from scratch.

Super simple to use

µRequest is designed to be a drop-in replacement for request. It supports HTTPS and follows redirects by default.

npm install --save @coolaj86/urequest

var request = require('@coolaj86/urequest');
request('http://www.google.com', function (error, response, body) {
  console.log('error:', error); // Print the error if one occurred
  console.log('statusCode:', response && response.statusCode); // Print the response status code if a response was received
  console.log('body:', body); // Print the HTML for the Google homepage.
});

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()
method - http method (default: "GET")
headers - http headers (default: {})

body - entity body for PATCH, POST and PUT requests. Must be a Buffer, String or ReadStream. If json is true, then body must be a JSON-serializable object.
json - sets body to JSON representation of value and adds Content-type: application/json header. Additionally, parses the response body as JSON.

followRedirect - follow HTTP 3xx responses as redirects (default: true). This property can also be implemented as function which gets response object as a single argument and should return true if redirects should continue or false otherwise.
followAllRedirects - follow non-GET HTTP 3xx responses as redirects (default: false)
followOriginalHttpMethod - by default we redirect to HTTP method GET. you can enable this property to redirect to the original HTTP method (default: false)
maxRedirects - the maximum number of redirects to follow (default: 10)
removeRefererHeader - removes the referer header when a redirect happens (default: false). Note: if true, referer header set in the initial request is preserved during redirect chain.

encoding - encoding to be used on setEncoding of response data. If null, the body is returned as a Buffer. Anything else (including the default value of undefined) will be passed as the encoding parameter to toString() (meaning this is effectively utf8 by default). (Note: if you expect binary data, you should set encoding: null.)

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 to it.

Note: request.defaults() does not modify the global request API; instead, it returns a wrapper that has your default settings applied to it.

Note: You can call .defaults() on the wrapper that is returned from request.defaults to add/override defaults that were previously defaulted.

For example:

//requests using baseRequest() will set the 'x-token' header
var baseRequest = request.defaults({
  headers: {'x-token': 'my-token'}
})

//requests using specialRequest() will include the 'x-token' header set in
//baseRequest and will also include the 'special' header
var specialRequest = baseRequest.defaults({
  headers: {special: 'special value'}
})

request.METHOD()

These HTTP method convenience functions act just like request() but with a default method already set for you:

request.get(): Defaults to method: "GET".
request.post(): Defaults to method: "POST".
request.put(): Defaults to method: "PUT".
request.patch(): Defaults to method: "PATCH".
request.del() / request.delete(): Defaults to method: "DELETE".
request.head(): Defaults to method: "HEAD".
request.options(): Defaults to method: "OPTIONS".

Debugging

There are at least two ways to debug the operation of request:

Launch the node process like NODE_DEBUG=urequest node script.js (lib,request,otherlib works too).
Set require('@coolaj86/urequest').debug = true at any time (this does the same thing as #1).