REST API Builder

This tutorial describes how to construct a REST API so that traffic queries and other scriptable features can be invoked remotely. Before proceeding with this tutorial it is worth studying the Scripting Queries tutorial since it introduces the scripting capabilities of Traffic Sentinel.

Note: This tutorial describes a feature that was added in Traffic Sentinel 6.0.39. If you are running an older version of Traffic Sentinel you will need to upgrade before you can use this.

Query Scripts Directory

REST-API query scripts should be added to:

/usr/local/inmsf/queries

You may need to log in to the server and create this directory before you start.

Example

Below is a simple example of a REST API query script:

// author: Neil McKee
// date: 2/12/2013
// version: 1.0
// description: query for host location
// ttl: 60
// resultFormat: json

if(!address) throw("missing address");
var net = Network.current();
var loc = net.locationMap([ address ]);
var locationZone = null;
var locationGroup = null;
var locationIF = null;
if(loc) {
  locationIF = loc[0];
  net.path = locationIF;
  locationZone = net.zone();
  locationGroup = net.group();
}
var ans = {
   "address": address,
      "zone": locationZone,
     "group": locationGroup,
      "port": locationIF,
};
println(JSON.stringify(ans));

Save this as /usr/local/inmsf/queries/location.js and then you can invoke it immediately like this:

http://<server>/inmsf/Q/location.js?address=<address>

where <server> is your traffic sentinel server and <address> can be any address (IP, MAC, IPv6, ...). The output should look like this:

{"address":"10.0.0.70","zone":"SF","group":"Lab","port":"10.0.0.239>2"}

Result Caching

The ttl: 60 comment at the top of the script directs the server to cache the result for 60 seconds.

Access Control

A comment such as AuthClients: 10.1.1.0/24,10.2.2.0/24 will restrict access to client IPs in those CIDRs.

Output Format

The resultFormat: <format> comment announces the output format, which controls the mime-type of the page. Options are txt,csv,json or html.

Traffic Query Example

Below is another example. This time it is a real-time traffic query that can only be accessed from client 10.0.0.114. The ttl is set to 60 seconds but the view: rttraffic comment means the server will invalidate the cache if new data is available for the rttraffic view.

// author: Peter Phaal
// date: 10/12/2012
// version: 1.0
// description: csv Query(view, select, where, interval, sort, n, group, headers)
// ttl: 60
// view: rttraffic
// resultFormat: csv
// authClients: 10.0.0.114

var view = "rttraffic";
var select   = typeof(select)   != 'undefined' ? select   : "sourceaddress,bytes";
var where    = typeof(where)    != 'undefined' ? where    : "";
var interval = typeof(interval) != 'undefined' ? interval : "last60minutes";
var sort     = typeof(sort)     != 'undefined' ? sort     : "bytes";
var n        = typeof(n)        != 'undefined' ? n        : "10";
var group    = typeof(group)    != 'undefined' ? group    : "";
var headers  = typeof(headers)  != 'undefined' ? headers  : false;

var max_n     = 100;
var max_range = 180;

try {
  if(!select) throw "missing select";
  if(!interval) throw "missing interval";
  if(!sort) throw "missing sort";
  if(!n) throw "missing n";

  if(n <= 0) throw "error n <= 0";
  if(n > max_n) throw "error n > " + max_n;

  var q = Query.topN(view,select,where,interval,sort,n);
  q.group = group;

  var times = q.timeRange();
  var now = (new Date()).getTime();
  if((Math.abs((now - times[0].getTime()) / 60000)) > max_range) throw "interval range";
  if((Math.abs((now - times[1].getTime()) / 60000)) > max_range) throw "interval range";

  var table = q.run();
  table.printCSV(headers);
} catch(err) {
  println("error = " + err);
}