A lightweight, zero-dependency drop-in replacement for request.js
Go to file
AJ ONeal 554890a809 add --save 2018-06-19 04:18:18 +00:00
examples initial commit 2018-06-18 19:39:19 -06:00
LICENSE initial commit 2018-06-18 19:39:19 -06:00
README.md add --save 2018-06-19 04:18:18 +00:00
index.js initial commit 2018-06-18 19:39:19 -06:00
package.json urequest => @coolaj86/urequest (someone just claimed it over the weekend) 2018-06-18 20:00:55 -06:00

README.md

µ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:

  1. Launch the node process like NODE_DEBUG=urequest node script.js (lib,request,otherlib works too).

  2. Set require('@coolaj86/urequest').debug = true at any time (this does the same thing as #1).