README
Main goal
This is a module to merge a few api calls into one to extremely decrease the number of AJAX requests on client. Also it allows to group responses easy. Imagine, we have a few apis:
- http://st1.craziegames.com:3000/api/users
- http://st1.craziegames.com:3000/api/users/id101
- http://st1.craziegames.com:3000/api/countries
- http://st1.craziegames.com:3000/api/countries/id402
- http://st1.craziegames.com:3000/api/customers
And we want to get data from client side about few users or users and some countries. That's easy! Instead of 3 AJAX Requests
http://st1.craziegames.com:3000/api/users/id101
http://st1.craziegames.com:3000/api/users/id102
http://st1.craziegames.com:3000/api/countries
You can make only ONE request
http://st1.craziegames.com:3001/api/resources?user1=api/users/id101&user2=api/users/id102&countries=api/countries
And receive
{"user1":"{\"id\":\"id101\",\"firstName\":\"Mike\",\"age\":21}","user2":"{\"id\":\"id102\",\"firstName\":\"Bob\",\"age\":22}","countries":"[{\"id\":\"id401\",\"countryName\":\"DENMARK\",\"countryCode\":\"DK\"},{\"id\":\"id402\",\"countryName\":\"UKRAINE\",\"countryCode\":\"UA\"},{\"id\":\"id403\",\"countryName\":\"USA\",\"countryCode\":\"US\"}]"}
Inside it uses a technology HTTP Pipelining so even if you are merging 100 API calls you'll get a result not later then slowest API call in a given set.
Installation
Here is few steps to start using the module
$ cd YOUR_PROJECT_NAME
$ npm install api-call-merger
Features
- Simple Integration
- Fast
- No memory leaks
- Easy to test
- Built-in security functions and limiters
Use
Start with adding these lines inside your code
var APICallMerger = require('api-call-merger');
var API = new APICallMerger( );
After you have to set prefix of your API:
API.setMainAPIUrl('/api/resources');
Attach an HTTP Object (from require('http'));
API.attachHttpObject(http);
If you want, you can set maximum number of url parameters ( in result query - groups )
API.setMaxUrlParams(100);
To filter some villains, module has a function that starts before a api call and allows or discards api execution. It's async so you can realizie logic with Redis, for example Rate Limiter and/or Black List
API.setSecureOptions(true, functionToCheckUsersTrustworthy);
// And example of this function:
function functionToCheckUsersTrustworthy(param1, callback) {
// After logic execution just call callback(true) to allow API request or callback(false) to discard
}
And final - add some routes and API URLs
API.addAPIRoute('API_NAME_IN_URL_PARAMETER', 'API_URL_FOR_REQUEST', IS_API_NAME_STRICT_OR_TEMPLATE? );
// To handle only api/users
API.addAPIRoute('api/users', 'http://st1.craziegames.com:3000/api/users', true);
// To handle api/users/id1, api/users/777, etc.
API.addAPIRoute('api/users/', 'http://st1.craziegames.com:3000/api/users/', false);
API.addAPIRoute('api/customers', 'http://st1.craziegames.com:3000/api/customers', true);
API.addAPIRoute('api/customers/', 'http://st1.craziegames.com:3000/api/customers/', false);
API.addAPIRoute('api/countries', 'http://st1.craziegames.com:3000/api/countries', true);
API.addAPIRoute('api/countries/', 'http://st1.craziegames.com:3000/api/countries/', false);
And call! That's all.
API.safeApiRequest(requestUrl, function(data) {
res.send(data);
}, 'param_to_secure_function');
How to test with Mocha and full project please browse on Github page https://github.com/doexclusive/api-call-merger-example
More info you can find also inside a code (index.js)
Examples
Main API url is http://st1.craziegames.com:3001/api/resources? Allowed APIs are:
api/users
api/users/id101
api/users/id102
api/users/id103
api/customers
api/customers/id301
api/customers/id302
api/customers/id303
api/countries
api/countries/id401
api/countries/id402
api/countries/id403
So the format is : http://st1.craziegames.com:3001/api/resources?groupName1=apiName1...groupNameN=apiNameN
More Examples
One
Call http://st1.craziegames.com:3001/api/resources?users=api/users/id101&customer=api/customers/id301&coutries=api/countries You'll get
{"users":"{\"id\":\"id101\",\"firstName\":\"Mike\",\"age\":21}","customer":"{\"id\":\"id301\",\"fullName\":\"Bill M.\",\"moneySpent\":10000}","coutries":"[{\"id\":\"id401\",\"countryName\":\"DENMARK\",\"countryCode\":\"DK\"},{\"id\":\"id402\",\"countryName\":\"UKRAINE\",\"countryCode\":\"UA\"},{\"id\":\"id403\",\"countryName\":\"USA\",\"countryCode\":\"US\"}]"}
Two
Call http://st1.craziegames.com:3001/api/resources?userOne=api/users/id101&userTwo=api/users/id102 You'll get
{"userOne":"{\"id\":\"id101\",\"firstName\":\"Mike\",\"age\":21}","userTwo":"{\"id\":\"id102\",\"firstName\":\"Bob\",\"age\":22}"}
Three
Call http://st1.craziegames.com:3001/api/resources?users=api/users&countries=api/countries You'll get
{"users":"[{\"id\":\"id101\",\"firstName\":\"Mike\",\"age\":21},{\"id\":\"id102\",\"firstName\":\"Bob\",\"age\":22},{\"id\":\"id103\",\"firstName\":\"John\",\"age\":23}]","countries":"[{\"id\":\"id401\",\"countryName\":\"DENMARK\",\"countryCode\":\"DK\"},{\"id\":\"id402\",\"countryName\":\"UKRAINE\",\"countryCode\":\"UA\"},{\"id\":\"id403\",\"countryName\":\"USA\",\"countryCode\":\"US\"}]"}