throttled-web-client
Throttled Web Client is an npm package for making throttled web requests in Javascript.
Internally, we use the request
npm package to make requests.
However, this package is structured into a class so that it can be extended and used in an object-oriented way!
Throttled Web Client also uses promises instead of callbacks.
This is ideal for when ou need to hit a rate-limited API without exceeding a certain limit. As a user, you will specify how many requests per unit of time you want to be throttled to. You're then able to create requests as fast as you want, but they'll only be sent at an appropriate interval.
Usage
Setup
In package.json
:
dependencies: {
"throttled-web-client": "^1",
...
}
In whatever file:
const ThrottledWebClient = require('throttled-web-client');
Instantiating the class
Since this is an ES6 class, it must be instantiated before it can be used.
const ThrottledWebClient = require('throttled-web-client');
const myApiWebClient = new ThrottledWebClient('https://myApi.com/');
To instantiate ThrottledWebClient
, you must pass in between 1 and 3 arguments.
The first argument, path
, is the base URL that will be used for all requests.
This argument is required.
If you want a generic web client that can hit any endpoint, pass in an empty string.
The second argument, requestsPerPeriod
, is a positive integer representing the maximum number of requests that can be made per period.
This argument is optional, and defaults to 5
.
The third argument, period
, is a positive integer representing the duration of a "period" in milliseconds.
This argument is optional, and defaults to 1000
, which is 1 second.
For example, the default arguments of requestsPerPeriod = 5
, period = 1000
mean that the client will make no more than 5 requests in any 1 second period.
Making an API call
const ThrottledWebClient = require('throttled-web-client');
const myApiWebClient = new ThrottledWebClient('https://myApi.com/');
const path = '/path/to/endpoint';
const options = {
/* request.js options object
see https://github.com/request/request
*/
}
myApiWebClient.request(path, options)
.then(response => {
console.log(response); // This will log the entire response.
});
Built-in formatting methods
There are 3 built-in methods that will parse the response to return the part you care about, in the format you want.
requestAsJson
: Converts thebody
property ofresponse
to JSON, and gives you the entireresponse
object.requestBody
: Gives you thebody
property ofresponse
, discarding the rest ofresponse
.requestBodyAsJson
: Converts thebody
property ofresponse
to JSON and gives you the converted body.
const ThrottledWebClient = require('javascript-web-client');
const myApiWebClient = new ThrottledWebClient('https://myApi.com/');
const path = '/path/to/endpoint';
const options = {
/* request.js options object
see https://github.com/request/request
*/
}
myApiWebClient.requestBodyAsJson(path, options)
.then(response => {
console.log(response); // This will log the response body, as an object.
});