3scale integration plugin for JavaScript/CoffeeScript/Node.js applications

3scale is an API Infrastructure service which handles API Keys, Rate Limiting, Analytics, Billing Payments and Developer Management. Includes a configurable API dashboard and developer portal CMS. More product stuff at http://www.3scale.net/, support information at http://support.3scale.net/.

Installation

The module is delivered through the package manager npm, so that the installation should be easy as: npm install 3scale

Requirements

Starting at version 0.6.0, this plugin requires using Node.js versions 0.10.x or higher.

Synopsis

This plugin supports the 3 main calls to the 3scale backend:

• authrep grants access to your API and reports the traffic on it in one call.
• authorize grants access to your API.
• report reports traffic on your API.

3scale supports 3 authentication modes: App Id, User Key and OAuth. The first two are similar on their calls to the backend, they support authrep. OAuth differs in its usage two calls are required: first authorize then report.

Usage

Authrep

Authrep is a 'one-shot' operation to authorize an application and report the associated transaction at the same time. The main difference between this call and the regular authorize call is that usage will be reported if the authorization is successful. Read more about authrep at the active docs page on the 3scale's support site.

Here is an example assuming that you are using the app_id/app_key authentication mode:

var Client = require('3scale').Client;

client = new Client("your provider key",["3Scale URL(default : su1.3scale.net)"],["proxy URL"]);

client.authrep({"app_id": "your application id", "app_key": "your application key", "usage": { "hits": 1 } }, function(response){
  console.log(response);
});

In case you have your API authentication configured in 3scale to use the user_key mode, this would be the equivalent to the example above:

var Client = require('3scale').Client;

client = new Client("your provider key");

client.authrep_with_user_key({ "user_key": "your key", "usage": { "hits": 1 } }, function(response){
  console.log(response);
});

Authorize and Report

You can alternatively use the authorize and report methods to do the same in two separate calls. Note that the report method supports sending the usage for multiple transactions in a single call.

var Client = require('3scale').Client;

client = new Client("your provider key");

client.authorize({ "app_id": "your application id", "app_key": "your application key" }, function(response){
  if (response.is_success()) {
    var trans = [{ "app_id": "your application id", "usage": { "hits": 3 } }];
    client.report(trans, function (response) {
      console.log(response);
    });
  } 
  else {
    console.log("Error: " + response.error_code + " msg: " + response.error_msg);
  }
});

Here is the same example for the user_key authentication pattern:

var Client = require('3scale').Client;

client = new Client("your provider key");

client.authorize_with_user_key({ "user_key": "your key" }, function(response){
  if (response.is_success()) {
    var trans = [{ "user_key": "your key", "usage": { "hits": 3 }}];
    client.report(trans, function (response) {
      console.log(response);
    });
  } 
  else {
    console.log("Error: " + response.error_code + " msg: " + response.error_msg);
  }
});

Note that the report method supports sending the usage for multiple transactions in a single call.

var trans = [
              { "app_id": "your application id", "usage": {"hits": 1}},
              { "app_id": "your application id", "usage": {"hits": 1000}}
             ]

client.report(trans, function(response){
  console.log(response);
});

OAuth

If you set OAuth as the authentication pattern for your API in 3scale, you will need to take the separate authorize and report approach (i.e. there is no authrep for OAuth).

var Client = require('3scale').Client;

client = new Client("your provider key");

client.oauth_authorize({"app_id": "your application id"}, function(response){
  if (response.is_success()) {
    var trans = [{"app_id": "your application id", "usage": {"hits": 3}}];
    client.report(trans, function (response) {
      console.log(response);
    });
  } 
  else {
    console.log("Error: " + response.error_code + " msg: " + response.error_msg);
  }
});

To test

To run tests: npm test or vows test/* --spec from the root directory of the project. Please note that you will first need to set the following environment variables using your own 3scale keys:

• TEST_3SCALE_PROVIDER_KEY
• TEST_3SCALE_APP_KEY
• TEST_3SCALE_APP_ID