{"_id":"@request/interface","_rev":"5-c6df340392f1234f029d4b1426073603","name":"@request/interface","description":"Common Interface for HTTP Clients","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@request/interface","version":"0.1.0","description":"Common Interface for HTTP Clients","keywords":["http","client","interface"],"license":"Apache-2.0","homepage":"https://github.com/request/interface","author":{"name":"Simeon Velichkov","email":"simeonvelichkov@gmail.com","url":"http://simov.github.io"},"repository":{"type":"git","url":"git+https://github.com/request/interface.git"},"dependencies":{},"devDependencies":{},"main":"index.js","files":["config/","LICENSE","README.md","index.js"],"scripts":{},"gitHead":"3e12802bf82a71792505e3a9ebea512c6e85fdbd","bugs":{"url":"https://github.com/request/interface/issues"},"_id":"@request/interface@0.1.0","_shasum":"c913504d3dc2810afad555b599aeaec2cc4c6768","_from":".","_npmVersion":"3.8.9","_nodeVersion":"6.0.0","_npmUser":{"name":"request","email":"request@outofindex.com"},"dist":{"shasum":"c913504d3dc2810afad555b599aeaec2cc4c6768","tarball":"https://registry.npmjs.org/@request/interface/-/interface-0.1.0.tgz","integrity":"sha512-eU+ccrwfht1uqoYN/fpDnjYFHm7MJJDCkUbEZHvVTdUR6PqDvfNuYkhRIQ/peIm3Jzq94duZgX5l2yTEToXfbw==","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCGxvjaAZGTtdn6QrGyErleD6lz4tIe1SdhMVbWjURf0wIgaCSOCyEFb9tsb+CNdurkjopdrr2YCWuiN9pvIj6D7rk="}]},"maintainers":[{"name":"request","email":"request@outofindex.com"}],"_npmOperationalInternal":{"host":"packages-12-west.internal.npmjs.com","tmp":"tmp/interface-0.1.0.tgz_1462274961727_0.5805139560252428"}}},"readme":"\n# Common Interface for HTTP Clients\n\nA module conforming to this specification is:\n\n1. A function that expects the common options object outlined in this specification\n2. A function that initiates the actual HTTP request while consuming the options outlined in this specification\n\n```js\nmodule.exports = (options) => {\n  // do something with options\n  // and make the actual HTTP request\n}\n```\n\nGiven the above module definition, a client application can use it like this:\n\n```js\nvar request = require('my-http-client')\n// make request\nrequest({\n  // any common option defined in this specification\n})\n```\n\n\n## HTTP Client Wrappers\n\n```js\nvar http = require('http')\n\nmodule.exports = (options) => {\n  // do something with the common interface options\n  var resultOptions = {}\n  // implement various HTTP features\n  return http.request(resultOptions)\n}\n```\n\n---\n\n```js\nvar request = require('request')\n\nmodule.exports = (options) => {\n  // do something with the common interface options\n  var resultOptions = {}\n  // implement various HTTP features\n  return request(resultOptions)\n}\n```\n\n---\n\n```js\n// use the native fetch API in the browser\n\nmodule.exports = (options) => {\n  // do something with the common interface options\n  var resultOptions = {}\n  // implement various HTTP features\n  return fetch(new Request(url, resultOptions))\n}\n```\n\nEither way the client application should be able to make requests in a consistent way:\n\n```js\nvar request = require('my-http-client')\n// make request\nrequest({\n  // any common option defined in this specification\n})\n```\n\n\n## Optional Dependencies\n\nA module conforming to this specification while having optional dependencies may look like this:\n\n```js\nmodule.exports = (deps) => (options) => {\n  var resultOptions = {}\n  if (options.oauth) {\n    resultOptions.oauth = deps.oauth(options.oauth)\n  }\n  return request(resultOptions)\n}\n```\n\nGiven the above module definition, a client application can use it like this:\n\n```js\nvar request = require('my-http-client')({\n  oauth: require('my-oauth-implementation')\n})\n// make request\nrequest({\n  // any common option defined in this specification\n})\n```\n\n\n## Bundled Dependencies\n\nA module conforming to this specification while having *hardcoded* dependencies may look like this:\n\n```js\nmodule.exports = require('my-http-client')({\n  oauth: require('my-oauth-implementation')\n})\n```\n\nGiven the above module definition, a client application can use it like this:\n\n```js\nvar request = require('my-http-client')\n// make request\nrequest({\n  // any common option defined in this specification\n})\n```\n\n\n## Basic API\n\nA module using the common [@request/api][request-api] may look like this:\n\n```js\nvar request = require('my-http-client')\nvar api = require('@request/api')\n\nmodule.exports = api({\n  type: 'basic',\n  request: request\n})\n```\n\nGiven the above module definition, a client application can use it like this:\n\n```js\nvar request = require('my-http-client')\n// make request\nrequest('url', {options}, (err, res, body) => {})\n// or\nrequest.[HTTP_VERB]('url', {options}, (err, res, bdoy) => {})\n// + any combination of the above arguments\n```\n\n\n## Chain API\n\nA module using the common [@request/api][request-api] may look like this:\n\n```js\nvar request = require('my-http-client')\nvar api = require('@request/api')\n\nmodule.exports = api({\n  type: 'chain',\n  config: {\n    method: {\n      get: [],\n      // ...\n    },\n    option: {\n      qs: [],\n      // ...\n    },\n    custom: {\n      submit: [],\n      // ...\n    }\n  },\n  define: {\n    submit: function (callback) {\n      if (callback) {\n        this._options.callback = callback\n      }\n      return request(this._options)\n    }\n  }\n})\n```\n\nGiven the above module definition, a client application can use it like this:\n\n```js\nvar request = require('my-http-client')\n// make request\nrequest\n  .get('url')\n  .qs({a: 1})\n  .submit((err, res, body) => {})\n```\n\n\n## Promises\n\nA module utilizing Promises may look like this:\n\n```js\nmodule.exports = (deps) => (options) => {\n  var request = deps.request\n\n  if (deps.promise) {\n    var Promise = deps.promise\n    var promise = new Promise((resolve, reject) => {\n      options.callback = (err, res, body) => {\n        if (err) {\n          reject(err)\n        }\n        else {\n          resolve([res, body])\n        }\n      }\n    })\n    request(options)\n    return promise\n  }\n  else {\n    return request(options)\n  }\n}\n```\n\nGiven the above module definition, a client application can use it like this:\n\n```js\nvar request = require('my-http-client')({\n  request: require('request'),\n  promise: Promise\n})\n// or\nvar request = require('my-http-client')({\n  request: require('request'),\n  promise: require('bluebird')\n})\n// make request\nrequest({options})\n  .catch((err) => {})\n  .then((result) => {})\n```\n\nPromises can be combined with the [@request/api][request-api].\n\n\n# Interface\n\noption    | type\n:---      | :---\nmethod    | `String`\n**URL**   |\nurl/uri   | `String`, `Object`\nqs        | `Object`, `String`\n**Body**  |\nform      | `Object`, `String`\njson      | `Object`, `String`\nbody      | `Stream`, `Buffer`, `Array`, `String`\nmultipart | `Object`, `Array`\n**Authentication** |\nauth      | `Object`\n | basic, oauth, hawk, httpSignature, aws\n**Modifiers** |\ngzip      | `Boolean`, `String`\nencoding  | `Boolean`, `String`\nstringify | `Object`\nparse     | `Object`\n**Proxy** |\nproxy     | `String`, `Object`\ntunnel    | `Boolean`\n**Misc**  |\nheaders   | `Object`\ncookie    | `Boolean`, `Object`\nlength    | `Boolean`\ncallback  | `Function`\nredirect  | `Boolean`, `Object`\ntimeout   | `Number`\nhar       | `Object`\nend       | `Boolean`\n\n\n---\n\n\n## Method\n\n### method `String`\n\n\n---\n\n\n## URL\n\n### url/uri `String` | `Object`\n  - `String`\n  - `url.Url`\n\n### qs `Object` | `String`\n  - `Object`\n  - `String`\n\n\n---\n\n\n## Body\n\n### form `Object` | `String`\n  - `Object`\n  - `String` pass URL encoded string if you want it to be RFC3986 encoded prior sending\n\n### json `Object` | `String`\n  - `Object`\n  - `String`\n\n### body `String` | `Buffer` | `Array` | `Stream`\n  - `Stream`\n  - `Buffer`\n  - `String`\n  - `Array`\n\n### multipart `Object` | `Array`\n\n- `Object` for `multipart/form-data`\n- `Array` for any other `multipart/[TYPE]`, defaults to `multipart/related`\n\nEach item's body can be either: `Stream`, `Request`, `Buffer` or `String`.\n\n- `_multipart`\n  - `data` - the above\nAdditionally you can set `preambleCRLF` and/or `postambleCRLF` to `true`.\n\n\n---\n\n\n## Authentication\n\n### auth `Object`\n  - `basic`\n    - `{user: '', pass: '', sendImmediately: false, digest: true}`\n      - Sets the `Authorization: Basic ...` header.\n      - The `sendImmediately` option default to `true` if omitted.\n      - The `sendImmediately: false` options requires the [redirect option][redirect-option] to be enabled.\n      - Digest authentication requires the [@request/digest][request-digest] module.\n\n  - `bearer`\n    - `{token: '', sendImmediately: false}`\n      - Alternatively the `Authorization: Bearer ...` header can be set if using the `bearer` option.\n      - The rules for the `sendImmediately` option from above applies here.\n\n  - `oauth`\n\n  - `hawk`\n\n  - `httpSignature`\n\n  - `aws`\n\n\n---\n\n\n## Modifiers\n\n### gzip `Boolean` | `String`\n- `true`\n  - Pipes the response body to [zlib][zlib] Inflate or Gunzip stream based on the compression method specified in the `content-encoding` response header.\n- `'gzip'` | `'deflate'`\n  - Explicitly specify decompression method to use.\n\n### encoding `Boolean` | `String`\n- `true`\n  - Pipes the response body to [iconv-lite][iconv-lite] stream, defaults to `utf8`.\n- `'ISO-8859-1'` | `'win1251'` | ...\n  - Specific encoding to use.\n- `'binary'`\n  - Set `encoding` to `'binary'` when expecting binary response.\n\n### parse `Object`\n  - `{json: true}`\n    - sets the `accept: application/json` header for the request\n    - parses `JSON` or `JSONP` response bodies *(only if the server responds with the approprite headers)*\n  - `{json: function () {}}`\n    - same as above but additionally passes a user defined reviver function to the `JSON.parse` method\n  - `{qs: {sep:';', eq:':'}}`\n    - [qs.parse()][qs] options to use\n  - `{querystring: {sep:';', eq:':', options: {}}}` use the [querystring][querystring] module instead\n    - [querystring.parse()][querystring] options to use\n\n### stringify `Object`\n  - `{qs: {sep:';', eq:':'}}`\n    - [qs.stringify()][qs] options to use\n  - `{querystring: {sep:';', eq:':', options: {}}}` use the [querystring][querystring] module instead\n    - [querystring.stringify()][querystring] options to use\n\n\n---\n\n\n## Proxy\n\n### proxy `String` | `Object`\n\n```js\n{\n  proxy: 'http://localhost:6767'\n  //\n  proxy: url.parse('http://localhost:6767')\n  //\n  proxy: {\n    url: 'http://localhost:6767',\n    headers: {\n      allow: ['header-name'],\n      exclusive: ['header-name']\n    }\n  }\n}\n```\n\n### tunnel `Boolean`\n  - `true`\n\n\n---\n\n\n## Misc\n\n### headers `Object`\n\n\n### cookie `Boolean` | `Object`\n  - `true`\n  - `new require('tough-cookie).CookieJar(store, options)`\n\n\n### length `Boolean`\n  - `true` defaults to `false` if omitted\n\n\n### callback `Function`\n  - `function (err, res, body) {}` buffers the response body\n    - by default the response buffer is decoded into string using `utf8`.\n    Set the `encoding` property to `binary` if you expect binary data, or any other specific encoding.\n\n\n### redirect `Boolean` | `Object`\n  - `true`\n    - follow redirects for `GET`, `HEAD`, `OPTIONS` and `TRACE` requests\n  - `Object`\n    - *all* - follow all redirects\n    - *max* - maximum redirects allowed\n    - *removeReferer* - remove the `referer` header on redirect\n    - *allow* - `function (res)` user defined function to check if the redirect should be allowed\n\n\n### timeout `Number`\n  - 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\n\n\n### har `Object`\n\n\n### end `Boolean`\n  - `true`\n    - tries to automatically end the request on `nextTick`\n\n\n---\n\n\n  [request-api]: https://github.com/request/api\n  [qs]: https://www.npmjs.com/package/qs\n  [querystring]: https://nodejs.org/dist/latest-v6.x/docs/api/querystring.html\n\n\n\n  [request]: https://github.com/request/request\n  [request-contributors]: https://github.com/request/request/graphs/contributors\n  [zlib]: https://iojs.org/api/zlib.html\n  [node-http-request]: https://nodejs.org/api/http.html#http_http_request_options_callback\n\n  [tough-cookie]: https://github.com/SalesforceEng/tough-cookie\n  [iconv-lite]: https://www.npmjs.com/package/iconv-lite\n  [hawk]: https://github.com/hueniverse/hawk\n  [aws-sign2]: https://github.com/request/aws-sign\n  [http-signature]: https://github.com/joyent/node-http-signature\n  [tunnel-agent]: https://github.com/mikeal/tunnel-agent\n\n  [request-core]: https://github.com/request/core\n  [request-headers]: https://github.com/request/headers\n  [request-digest]: https://github.com/request/digest\n  [request-oauth]: https://github.com/request/oauth\n  [request-multipart]: https://github.com/request/multipart\n  [request-log]: https://github.com/request/log\n\n  [redirect-option]: #redirect\n","maintainers":[{"name":"request","email":"request@outofindex.com"},{"name":"simov","email":"simeonvelichkov@gmail.com"}],"time":{"modified":"2022-06-12T23:08:39.753Z","created":"2016-05-03T11:29:23.911Z","0.1.0":"2016-05-03T11:29:23.911Z"},"homepage":"https://github.com/request/interface","keywords":["http","client","interface"],"repository":{"type":"git","url":"git+https://github.com/request/interface.git"},"author":{"name":"Simeon Velichkov","email":"simeonvelichkov@gmail.com","url":"http://simov.github.io"},"bugs":{"url":"https://github.com/request/interface/issues"},"license":"Apache-2.0","readmeFilename":"README.md","users":{"warraven":true}}