Common Interface for HTTP Clients
A module conforming to this specification is:
- A function that expects the common options object outlined in this specification
- A function that initiates the actual HTTP request while consuming the options outlined in this specification
module.exports = (options) => {
}
Given the above module definition, a client application can use it like this:
var request = require('my-http-client')
request({
})
HTTP Client Wrappers
var http = require('http')
module.exports = (options) => {
var resultOptions = {}
return http.request(resultOptions)
}
var request = require('request')
module.exports = (options) => {
var resultOptions = {}
return request(resultOptions)
}
module.exports = (options) => {
var resultOptions = {}
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')
request({
})
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')
})
request({
})
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')
request({
})
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')
request('url', {options}, (err, res, body) => {})
request.[HTTP_VERB]('url', {options}, (err, res, bdoy) => {})
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')
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
})
var request = require('my-http-client')({
request: require('request'),
promise: require('bluebird')
})
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
qs 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
body String
| Buffer
| Array
| Stream
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
{qs: {sep:';', eq:':'}}
{querystring: {sep:';', eq:':', options: {}}}
use the querystring module instead
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
Misc
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