Node based convenience class for creating asynchronous API requests.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

build status api_request

Simple library for defining API requests asynchronously. Creates readable requests using a fuild chainable interface. Detects the content type and decodes it accordingy (currently available for application/json and application/x-www-form-urlencoded). Also, if one specifies the content type, a JS object may be passed in and it will be converted to the proper format by the proper content encoder.


At your command prompt type:

npm install api_request


Just include the library and start building requests:

var api_request = require('api_request');

var r = new api_request('http', '');
r.get('/').on('reply', function(reply, res) {

Also, you could make a request over SSL with basic authentication:

var r = new api_request('https', '');
r.with_basic_auth('ada', '4d4').
  get('/index.php').on('reply', function(reply, res) {

Or, you could post a JSON object over HTTPS with basic authentication:

var r = new api_request('https', '');
  with_basic_auth('ada', '4d4').
  with_payload({'greeting': 'hi'}).
  post('/index.php').on('reply', function(reply, res) {

Currently the only supported protocols are http or https. If someone wrote a module for another protocol that could be used as well, since it loads the module via a require statement.

It supports the four basic http verbs: 'GET', 'POST'. 'PUT', 'DELETE'.

Headers can be set like so:

var r = new api_request('http', '');
r.add_headers({'X-Orginating-IP': ''}).
  get('/index.php').on('reply', function(reply, res) {

Multiple headers can be set at once.

Content Encoders and Handlers

If the API you use this with requests or replies with a different format from x-www-form-urlencoded or json, the library can be extended by providing a content encoder or content handler object. It's quite simple, actually:

var r = new api_request('https', '');
  'appplication/rss+xml': function(data) {
    return decoded_data;

To send a different encoding, it goes like this:

var r = new api_request('https', '');
  'appplication/rss+xml': function(data) {
    return encoded_data;

More than one type of encoder or handler can be added at a time.


  • get(uri)
  • post(uri)
  • put(uri)
  • del(uri)
  • with_payload(data) -- chainable
  • with_basic_auth(user, pass) -- chainable
  • add_headers(headers_object) -- chainable
  • add_content_encoders(encoder_object)
  • add_content_handlers(handler_object)
  • set_length(bytes) -- chainable