request

interface

Common Interface for HTTP Clients

5
3
5
2
JavaScript
public
View on GitHub

Common Interface for HTTP Clients

Table of Contents

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:':'}}
  • {querystring: {sep:';', eq:':', options: {}}} use the querystring module instead

stringify Object

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

  • 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
v0.3.3[beta]