request/interface

Name: interface

Owner: request

Description: Common Interface for HTTP Clients

Created: 2016-05-02 11:53:19.0

Updated: 2017-05-18 23:06:12.0

Pushed: 2016-05-03 17:31:23.0

Homepage: null

Size: 17

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

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

le.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:

request = require('my-http-client')
ake request
est({
 any common option defined in this specification

HTTP Client Wrappers

http = require('http')

le.exports = (options) => {
 do something with the common interface options
r resultOptions = {}
 implement various HTTP features
turn http.request(resultOptions)

s
request = require('request')

le.exports = (options) => {
 do something with the common interface options
r resultOptions = {}
 implement various HTTP features
turn request(resultOptions)

s
se the native fetch API in the browser

le.exports = (options) => {
 do something with the common interface options
r resultOptions = {}
 implement various HTTP features
turn fetch(new Request(url, resultOptions))

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

request = require('my-http-client')
ake request
est({
 any common option defined in this specification

Optional Dependencies

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

le.exports = (deps) => (options) => {
r resultOptions = {}
 (options.oauth) {
resultOptions.oauth = deps.oauth(options.oauth)

turn request(resultOptions)

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

request = require('my-http-client')({
uth: require('my-oauth-implementation')

ake request
est({
 any common option defined in this specification

Bundled Dependencies

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

le.exports = require('my-http-client')({
uth: require('my-oauth-implementation')

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

request = require('my-http-client')
ake request
est({
 any common option defined in this specification

Basic API

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

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

le.exports = api({
pe: 'basic',
quest: request

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

request = require('my-http-client')
ake request
est('url', {options}, (err, res, body) => {})
r
est.[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:

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

le.exports = api({
pe: 'chain',
fine: {
request: request

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

request = require('my-http-client')
ake request
est
et('url')
s({a: 1})
allback((err, res, body) => {})
equest()

Promises

A module utilizing Promises may look like this:

le.exports = (deps) => (options) => {
r request = deps.request
r Promise = deps.promise

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


quest(options)
turn promise

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

request = require('my-http-client')({
quest: require('request'),
omise: Promise

r
request = require('my-http-client')({
quest: require('request'),
omise: require('bluebird')

ake request
est({options})
atch((err) => {})
hen((result) => {})

Basic and Chain APIs + Promises

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

api = require('@request/api')

le.exports = (deps) => api({
pe: 'basic', // or 'chain'
fine: {
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:

request = require('my-http-client')({
quest: require('request'),
omise: Promise

ET http://localhost:6767?a=1
est.get('http://localhost:6767', {qs: 1})
atch((err) => {})
hen((result) => {})
r
est
et('http://localhost:6767')
s({a: 1})
equest()
atch((err) => ())
hen((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

oxy: 'http://localhost:6767'

oxy: url.parse('http://localhost:6767')

oxy: {
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

---