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.

Managing REST API Scripts

The File>REST page is used to manage REST API scripts. Accessing this page typically requires administrator privileges. Click on the Upload button at the bottom of table to install a new script (the script must have a .js suffix).

Click on the Edit action to the right of a script to view and edit its contents:

Edit the text in the form and click the Test button to run the script to see output and identify any errors. Once the changes are working, click Save Changes to update the script.

Click on the Statistics option to see statistics about the operation of the scripts:

Statistics include: the number of queries, number of times the result could be served from cache, average time to run a query, total CPU time, errors, last time a query was run, and the last time the script was modified.

The Running option shows any queries that are currently runnning:

The form has buttons to kill queries that are taking too long, or consuming too many resources.

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
// inputs: address
// ttl: 60
// resultFormat: json

var address = address || "127.0.0.1";
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));

To install this script, either save location.js to your desktop and click the Upload button to install the script, or click on the New button to create a new script:

Fill in the details and click on the Submit button to create a new script. Click on the Edit button next to the script and paste in the code.

The script can now be invoked as:

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.

The view: traffic comment at the top of the Traffic Query Example below means the server will invalidate the cache if new data is available for the database view being queried.

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.

Alternatively, comments authUser: user and authPasswd: pass will require the client to supply that user and password via HTTP basic authentication. The use of basic authentication may imply that only https should be used to access the API. If so, that can be controlled in the apache config (see /etc/httpd/conf.d/inmsf_httpd.conf).

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

// author: Peter Phaal
// date: 4/20/2016
// version: 1.0
// description: Traffic query with CSV output
// inputs: select,where,interval,sort,n,group,headers
// ttl: 60
// view: traffic
// resultFormat: csv
// authClients: 10.0.0.0/8

var view = "traffic";
var select   = select   || "sourceaddress,bytes";
var where    = where    || "";
var interval = interval || "last60minutes";
var sort     = sort     || "bytes";
var n        = n        || "10";
var group    = group    || "";
var headers  = headers  || false;

var max_n     = 100;
var max_range = 180;

try {
  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);
}

This time it is a real-time traffic query that can only be accessed from clients in the 10.0.0.0/8 address range. The ttl is set to 60 seconds but the view: traffic comment means the server will invalidate the cache if new data is available for the traffic view.