javascript-studioStudio JSON Request
📡 A tiny Node HTTP(S) request wrapper for JSON APIs.
- Transparent JSON request / response handling
- Timeout support
- Status code validation and default validation for 2xx responses
- Follows redirects, but only once
- Unified error handling with status codes
- Consistent logging with Studio Log
Usage
const request = require('@studio/json-request');
request({
method: 'POST',
hostname: 'some-host',
path: '/some-path',
timeout: 5000
}, { some: 'payload' }, (err, data, res) => {
// ...
});
API
request(options[, data], callback): Creates a new HTTPS request, passing theoptionsto Node http.request, except for these properties:protocol: The protocol to use. Must be either"http:"or"https:". Defaults to"https:".timeout: The number of milliseconds after which the request should time out, causing enE_TIMEOUTerror.expect: The expected status code(s). This can be a number or an array of numbers.stream: Iftrue, thecallbackis invoked with(null, res)once the header was retrieved to allow to stream the response.log: A parent logger to use for the "Request" logger.
Behavior
- If the
timeoutoption is specified, a timer is installed which will abort the request and invoke the callback with an error. - If the
expectoption is specified, it validates the response HTTP status code. If it's a number the status code has to equal that number. If an array is given, any number in the array is accepted. If the option is not given, the request will fail for non2xxstatus codes. - If the
streamoption is specified, the response is returned immediately after the status code was checked. No further response processing is done by this library. It is the callers responsibility to consume the response. - If
datais given, it is stringified and passed as the request body and the request is sent. TheContent-Typeheader is set toapplication/json, unless this header was already provided. TheContent-Lengthis set to the request body length. - If
datais set tonull, the request is sent without a body. - If
datais omitted, the request object is returned and it's the callers responsibility to invokereq.end()to complete the request.
Callback
The callback is invoked with (err, data, response).
err: An error object ornull. The error will have acodeproperty with these possible string values:E_TIMEOUT: The request timed out.E_EXPECT: The response status code does not match the expectation. ThestatusCodeproperty on the error object is set to the response status code.E_JSON: Could not parse the response body as JSON. In this casedatais the raw body.E_ERROR: If anerrorevent was thrown.
data: The parsed response data, or if it could not be parsed the raw body.response: The response object.
Logging
Every request produces a log entry when the response was processed with this data:
request:protocol: The protocol usedmethod: The request method usedhost: The host namepath: The pathheaders: The request headers, if anyport: The port, if specifiedbody: The request body, if given
response:statusCode: The response status codeheaders: The response headersbody: The response body, if available
ms_head: The time it took to receive the response headerms_body: The time it took to receive the response body
If stream was set, the log entry is produced once the response header was
received without the response and ms_body properties, and another log entry
is produced when the response body was received with ms_body.
To remove confidential information from the logs, you can use Studio Log X. For example, you can X-out all Authorization headers from the logs like this:
const logger = require('@studio/log');
const Console = require('@studio/log-format/console');
const logX = require('@studio/log-x');
// Install filter on namespace "Request":
logger
.pipe(logX('request.headers.Authorization'))
.pipe(new Console());
Related modules
- 🎮 Studio CLI this module was initially developed for the JavaScript Studio command line tool.
- 👻 Studio Log is used for logging.
- ❎ Studio Log X can be use to X-out confidential information from the logs.
- 📦 Studio Changes is used to create the changelog for this module.
License
MIT
Made with ❤️ on 🌍