Common Interface for HTTP Clients

A module conforming to this specification is:

1. A function that expects the common options object outlined in this specification
2. A function that initiates the actual HTTP request while consuming the options outlined in this specification

module.exports = (options) => {
  // do something with options
  // and make the actual HTTP request
}

Given the above module definition, a client application can use it like this:

var request = require('my-http-client')
// make request
request({
  // any common option defined in this specification
})

HTTP Client Wrappers

var http = require('http')

module.exports = (options) => {
  // do something with the common interface options
  var resultOptions = {}
  // implement various HTTP features
  return http.request(resultOptions)
}

var request = require('request')

module.exports = (options) => {
  // do something with the common interface options
  var resultOptions = {}
  // implement various HTTP features
  return request(resultOptions)
}

// use the native fetch API in the browser

module.exports = (options) => {
  // do something with the common interface options
  var resultOptions = {}
  // implement various HTTP features
  return fetch(new Request(url, resultOptions))
}

Either way the client application should be able to make requests in a consistent way:

var request = require('my-http-client')
// make request
request({
  // any common option defined in this specification
})

Optional Dependencies

A module conforming to this specification while having optional dependencies may look like this:

module.exports = (deps) => (options) => {
  var resultOptions = {}
  if (options.oauth) {
    resultOptions.oauth = deps.oauth(options.oauth)
  }
  return request(resultOptions)
}

Given the above module definition, a client application can use it like this:

var request = require('my-http-client')({
  oauth: require('my-oauth-implementation')
})
// make request
request({
  // any common option defined in this specification
})

Bundled Dependencies

A module conforming to this specification while having hardcoded dependencies may look like this:

module.exports = require('my-http-client')({
  oauth: require('my-oauth-implementation')
})

Given the above module definition, a client application can use it like this:

var request = require('my-http-client')
// make request
request({
  // any common option defined in this specification
})

Basic API

A module using the common @request/api may look like this:

var request = require('my-http-client')
var api = require('@request/api')

module.exports = api({
  type: 'basic',
  request: request
})

Given the above module definition, a client application can use it like this:

var request = require('my-http-client')
// make request
request('url', {options}, (err, res, body) => {})
// or
request.[HTTP_VERB]('url', {options}, (err, res, bdoy) => {})
// + any combination of the above arguments

Chain API

A module using the common @request/api may look like this:

var request = require('my-http-client')
var api = require('@request/api')

module.exports = api({
  type: 'chain',
  config: {
    method: {
      get: [],
      // ...
    },
    option: {
      qs: [],
      // ...
    },
    custom: {
      submit: [],
      // ...
    }
  },
  define: {
    submit: function (callback) {
      if (callback) {
        this._options.callback = callback
      }
      return request(this._options)
    }
  }
})

Given the above module definition, a client application can use it like this:

var request = require('my-http-client')
// make request
request
  .get('url')
  .qs({a: 1})
  .submit((err, res, body) => {})

Promises

A module utilizing Promises may look like this:

module.exports = (deps) => (options) => {
  var request = deps.request

  if (deps.promise) {
    var Promise = deps.promise
    var promise = new Promise((resolve, reject) => {
      options.callback = (err, res, body) => {
        if (err) {
          reject(err)
        }
        else {
          resolve([res, body])
        }
      }
    })
    request(options)
    return promise
  }
  else {
    return request(options)
  }
}

Given the above module definition, a client application can use it like this:

var request = require('my-http-client')({
  request: require('request'),
  promise: Promise
})
// or
var request = require('my-http-client')({
  request: require('request'),
  promise: require('bluebird')
})
// make request
request({options})
  .catch((err) => {})
  .then((result) => {})

Promises can be combined with the @request/api.

Interface

option | type :--- | :--- method | String URL | url/uri | String, Object qs | Object, String Body | form | Object, String json | Object, String body | Stream, Buffer, Array, String multipart | Object, Array Authentication | auth | Object | basic, oauth, hawk, httpSignature, aws Modifiers | gzip | Boolean, String encoding | Boolean, String stringify | Object parse | Object Proxy | proxy | String, Object tunnel | Boolean Misc | headers | Object cookie | Boolean, Object length | Boolean callback | Function redirect | Boolean, Object timeout | Number har | Object end | Boolean

Method

method String

URL

url/uri String | Object

• String
• url.Url

qs Object | String

• Object
• String

Body

form Object | String

• Object
• String pass URL encoded string if you want it to be RFC3986 encoded prior sending

json Object | String

• Object
• String

body String | Buffer | Array | Stream

• Stream
• Buffer
• String
• Array

multipart Object | Array

• Object for multipart/form-data
• Array for any other multipart/[TYPE], defaults to multipart/related

Each item's body can be either: Stream, Request, Buffer or String.

• _multipart
  • data - the above Additionally you can set preambleCRLF and/or postambleCRLF to true.

Authentication

auth Object

• basic

  • {user: '', pass: '', sendImmediately: false, digest: true}
    • Sets the Authorization: Basic ... header.
    • The sendImmediately option default to true if omitted.
    • The sendImmediately: false options requires the redirect option to be enabled.
    • Digest authentication requires the @request/digest module.

• bearer

  • {token: '', sendImmediately: false}
    • Alternatively the Authorization: Bearer ... header can be set if using the bearer option.
    • The rules for the sendImmediately option from above applies here.

• oauth

• hawk

• httpSignature

• aws

Modifiers

gzip Boolean | String

• true
  • Pipes the response body to zlib Inflate or Gunzip stream based on the compression method specified in the content-encoding response header.
• 'gzip' | 'deflate'
  • Explicitly specify decompression method to use.

encoding Boolean | String

• true
  • Pipes the response body to iconv-lite stream, defaults to utf8.
• 'ISO-8859-1' | 'win1251' | ...
  • Specific encoding to use.
• 'binary'
  • Set encoding to 'binary' when expecting binary response.

parse Object

• {json: true}
  • sets the accept: application/json header for the request
  • parses JSON or JSONP response bodies (only if the server responds with the approprite headers)
• {json: function () {}}
  • same as above but additionally passes a user defined reviver function to the JSON.parse method
• {qs: {sep:';', eq:':'}}
  • qs.parse() options to use
• {querystring: {sep:';', eq:':', options: {}}} use the querystring module instead
  • querystring.parse() options to use

stringify Object

• {qs: {sep:';', eq:':'}}
  • qs.stringify() options to use
• {querystring: {sep:';', eq:':', options: {}}} use the querystring module instead
  • querystring.stringify() options to use

Proxy

proxy String | Object

{
  proxy: 'http://localhost:6767'
  //
  proxy: url.parse('http://localhost:6767')
  //
  proxy: {
    url: 'http://localhost:6767',
    headers: {
      allow: ['header-name'],
      exclusive: ['header-name']
    }
  }
}

tunnel Boolean

• true

Misc

headers Object

cookie Boolean | Object

• true
• new require('tough-cookie).CookieJar(store, options)

length Boolean

• true defaults to false if omitted

callback Function

• function (err, res, body) {} buffers the response body
  • by default the response buffer is decoded into string using utf8. Set the encoding property to binary if you expect binary data, or any other specific encoding.

redirect Boolean | Object

• true
  • follow redirects for GET, HEAD, OPTIONS and TRACE requests
• Object
  • all - follow all redirects
  • max - maximum redirects allowed
  • removeReferer - remove the referer header on redirect
  • allow - function (res) user defined function to check if the redirect should be allowed

timeout Number

• integer indicating the number of milliseconds to wait for a server to send response headers (and start the response body) before aborting the request. Note that if the underlying TCP connection cannot be established, the OS-wide TCP connection timeout will overrule the timeout option

har Object

end Boolean

• true
  • tries to automatically end the request on nextTick