Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Node based convenience class for creating asynchronous API requests.
branch: master

Merge pull request #2 from travis4all/clean

The repo your repo could be like!
latest commit 3c3713d993
@adaburrows authored

build status


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
Something went wrong with that request. Please try again.