Common Interface for HTTP Clients

Table of Contents

• Basic Module
• HTTP Client Wrappers
• Optional Dependencies
• Bundled Dependencies
• Basic API
• Chain API
• Promises
• Basic and Chain APIs + Promises
• Interface

Basic Module

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',
  define: {
    request: request
  }
})

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})
  .callback((err, res, body) => {})
  .request()

Promises

A module utilizing Promises may look like this:

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

  var promise = new Promise((resolve, reject) => {
    options.callback = (err, res, body) => {
      ;(err) ? reject(err) : resolve([res, body])
    }
  })

  request(options)
  return promise
}

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) => {})

Basic and Chain APIs + Promises

A module utilizing the common @request/api and Promises may look like this:

var api = require('@request/api')

module.exports = (deps) => api({
  type: 'basic', // or 'chain'
  define: {
    request: (options) => {
      var request = deps.request
      var Promise = deps.promise

      var promise = new Promise((resolve, reject) => {
        options.callback = (err, res, body) => {
          ;(err) ? reject(err) : resolve([res, body])
        }
      })

      request(options)
      return promise
    }
  }
})

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

var request = require('my-http-client')({
  request: require('request'),
  promise: Promise
})
// GET http://localhost:6767?a=1
request.get('http://localhost:6767', {qs: 1})
  .catch((err) => {})
  .then((result) => {})
// or
request
  .get('http://localhost:6767')
  .qs({a: 1})
  .request()
  .catch((err) => ())
  .then((result) => ())

---

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

---