bananatag-api v0.1.0
Node Library for the Bananatag API
Installation
$ npm install bananatag-api
Request
This library has a single method that requires either three or four parameters:
/**
* Check data and setup makeRequest
* @param {string} endpoint
* @param {object} params
* @param {object|function} options
* @param {bool} options.getAllResults
* @param {function} callback
*/
BtagAPI.request = function (endpoint, params, options, callback) {};
Endpoint {String}
Please see documentation for endpoints.
Parameters {Object}
Please see documentation for each endpoints parameters
Options {Object}
Currently, this library only supports a single option:
var options = {getAllResults: false};
For more information see pagination below.
Callback (with response parameters)
The callback parameter in the request
method handles the response.
/**
* @param {string} err
* @param {string} data JSON string
* @param {int} cursor Where the returned results end and the next request should start.
* @param {int} total Total records
*/
var callback = function (err, data, cursor, total) {
console.log(cursor); // used to fetch the next page manually (see below)
console.log(total); // used to fetch the next page manually
};
btag.request(
endPoint, // The request endpoint
params, // The request parameters
{getAllResults: false}, // If options are set then the callback is the next param
callback
)
####Pagination
Response data from the API is paginated. This library can assist with retrieving a single page at a time or getting all pages at once. To automatically fetch the next page until all results have been returned, use set options.getAllResults = true
before making the request. The API restricts requests to 1 per second so this library delays each request accordingly.
See examples below.
Usage
Get All Tags
var BTagAPI = require('bananatag-api');
var btag = new BTagAPI('Your AuthID', 'Your Key');
btag.request('tags', {}, function (err, data) {
if (!err) {
console.log(data);
}
});
Get Aggregate Stats Over Date-Range
var params = {
start: '2013-01-01',
end: '2014-03-30',
aggregateData: true
};
btag.request('tags', params, function (err, data) {
if (!err) {
console.log(data);
}
});
Automatically fetch the next page of results
To automatically get all pages a result, pass in an options argument into the third parameter of the .request method.
Set getAllResults
property of this parameter to true (defaults to false).
btag.request('tags', params, {getAllResults: true}, function (err, data, cursor, total) {
console.log(cursor);
console.log(total);
});
Manually fetch the next page of results
To manually get the next page, set params.next = cursor
(cursor
is returned from API). Or, if you are
making the request in the same session, you can simply call btag.request
again.
// Simple function to demonstrate manually retrieving the next page of results.
var params = {
start: '2013-01-01',
end: '2014-03-30',
next: 0 // Default value is 0
};
function getTags(i) {
btag.request('tags', params, {getAllResults: true}, function (err, data, cursor, total) {
if (i <= 1 && cursor < total) {
setTimeout(function() {
getTags((i += 1));
}, 1200);
}
});
}
getTags(0);
Running Tests
To run the test suite first invoke the following command within the repo, installing the development dependencies:
$ npm install
then run the tests:
$ npm test
License
Licensed under the MIT License.