A facility that simplifies making http requests both on promise and callback approaches.
Performs generic HTTP request
Params:
path<String>
- Full request url or pathopts<Object?>
- Optional request optionsbody<(String|Object)?>
- Optional request body, in case of json encoding it can be also objectheaders<Object<String, String>?>
Optional request headersmethod<String?>
- Optional http method, currently supportedget
,head
,post
,put
,patch
,delete
,options
. Default value isget
redirect<Boolean?>
- Optional, follow redirects or treat them as errors, default is treat as erroragent<http.Agent?>
- Optional user agentcompress<Boolean?>
- Optional, support gzip/deflate content encodingtimeout<Number?>
- Optional request timeout, default is opt provided in fac setup (3s)encoding<(String|Object)?>
- Optional request and response encoding, if string is provided it applies to both request and response. Default encoding is text for both request and responsereq<String?>
- Optional request body encoding, supported:json
andtext
. If no value is provided it will be treated as textres<String?>
- Optional response body encoding, supported:json
,text
andraw
. If no value is provided it will be treated as text, if unsupported value is provided it will return buffer. If value israw
then body stream is returned, useful for file downloads
cb<Function?>
- Optional callback function, if not provided call will be treated as promise
Response:
Promise<{ body: any, headers: object }>|void
- Server response, promise or callback result
Examples:
// GET
const { body, headers } = await fac.request('https://example.com')
// POST
const { body, headers } = await fac.request('https://example.com/submit', { method: 'post', body: { foo: 'bar' }, encoding: 'json' })
// OPTIONS
const { headers } = await fac.request('https://api-pub.bitfinex.com/v2/conf/pub:list:currency', { method: 'options' })
// Callback
fac.request(
'/data/store',
{ method: 'patch', body: 'test=33&foo=bar', headers: { 'content-type': 'application/x-www-form-urlencoded' } },
(err, resp) => {
...
})
// Request without options
fac.request('/data', (err, resp) => {
...
})
// error handling
fac.request('/data/store', (err) => {
console.log(err.message) // ERR_HTTP: 500 - Internal Server Error
console.log(err.status) // 500
console.log(err.statusText) // Internal Server Error
console.log(err.response) // { auth: 'failed' }
})
// file download
const eos = require('end-of-stream')
const { body: resp } = await fac.request('/file', { encoding: { res: 'raw' } }) // raw means return stream
await new Promise((resolve, reject) => {
const writer = fs.createWriteStream(writefile)
eos(writer, (err) => err ? reject(err) : resolve())
resp.pipe(writer)
})
Performs HTTP GET request
Params:
- Same as in request method just without
method
param
Response:
- Same as in request method
Example:
await fac.get('https://api-pub.bitfinex.com/v2/conf/pub:list:currency')
Performs HTTP POST request
Params:
- Same as in request method just without
method
param
Response:
- Same as in request method
Example:
const FormData = require('form-data')
const form = new FormData();
form.append('a', 1);
const reqOpts = {
body: form,
headers: form.getHeaders()
}
await fac.post('/submit', reqOpts)
Performs HTTP PUT request
Params:
- Same as in request method just without
method
param
Response:
- Same as in request method
Example:
const reqOpts = {
body: JSON.stringify({ a: 1 }),
headers: {
'Content-Type': 'application/json'
}
}
await fac.put('/data/store', reqOpts)
Performs HTTP PATCH request
Params:
- Same as in request method just without
method
param
Response:
- Same as in request method
Example:
const reqOpts = {
body: { a: 1 },
encoding: 'json'
}
await fac.patch('/data/store', reqOpts)
Performs HTTP DELETE request
Params:
- Same as in request method just without
method
param
Response:
- Same as in request method
Example:
const reqOpts = {
body: JSON.stringify({ id: 31 }),
headers: {
'Content-Type': 'application/json'
}
}
await fac.delete('/books', reqOpts)
Performs HTTP HEAD request
Params:
- Same as in request method just without
method
param
Response:
- HTTP response headers
Example:
const { headers } = await fac.head('https://api-pub.bitfinex.com/v2/conf/pub:list:currency')
console.log(headers['content-type']) // 'application/json; charset=utf-8'
Performs HTTP OPTIONS request
Params:
- Same as in request method just without
method
param
Response:
- HTTP response headers
Example:
const { headers } = await fac.head('https://api-pub.bitfinex.com/v2/conf/pub:list:currency')
console.log(headers['allow']) // 'GET,PUT,POST'