Ok there is a "concept" (I haven't added that many query types) API available in 0.04.17a (the current development release which also includes the new DNS tests which are in alpha).
There is no documentation but for anyone who would like to have a play and let me know of any obvious problems etc with it here is some information...
Calling the API
You call the API in your web page (JS) or script (XML) by an HTTP request to the api.php script with various query variables passed
Security
You have the following options... By default only an authenticated session can use the API. This means you can either navigate to it, JS will work ok as long as your browser is logged into FreeNATS or you can manually hack a login (unsupported) via HTTP requests to the relevant pages.
In order to allow general use of the API by unauthenticated browsers you must set the variable api.public to 1.
At this point ANYONE can use the API.
You can now optionally set the variable api.key to something (alphanumeric). If you do then you MUST PASS this key in the url as apikey.
Mode
The variable mode is either xml or js (will default to xml if unset will break if anything else). See below for output descriptions.
Query
Queries are passed as an array in the URL of query[X] and if required param[X]. In this early API the query types supported are:
- alerts - no paramer, returns all current alerts
node - nodeid as parameter, returns all relevant node information
test - testid as parameter, returns all relevant test information
api.php?mode=xml&apikey=FISH&query[0]=alerts&query[1]=node¶m[1]=NODEID
Would execute two queries - query 0 being an alert list and query 1 being the node info for NODEID
XML Output
XML Output is something like as follows (for an querts query when there are no alerts and for the nodeid bob in query 1:
<freenats-data>
<alerts count="0" query="0">
</alerts>
<node nodeid="bob" query="1">
<nodeid>bob</nodeid>
<nodename>bob</nodename>
<nodedesc>Bob</nodedesc>
<hostname>10.0.10.248</hostname>
<nodeenabled>1</nodeenabled>
<pingtest>0</pingtest>
<pingfatal>0</pingfatal>
<alertlevel>0</alertlevel>
<nodeicon></nodeicon>
<weight>11</weight>
<nodealert>0</nodealert>
<scheduleid>0</scheduleid>
<name>bob</name>
<alerttext>Passed</alerttext>
</node>
</freenats-data>
You are then free to parse this data etc.
JavaScript Output
mode=js will output a new JavaScript array containing pretty much the same information as XML but in a slightly different format (owing to JS's array index limitations etc). This will be in a data object called fnd_SOMERANDOM unless the variable dataid is specified in which case the data object will have this name.
If you specify a callback variable then the JS will exit by calling this function and passing the data object to it. In this way your script can build the query, output the remote script tags and then be called once output is complete.
For the same example as above the following JS is generated:
var fnd_76af489a76=new Array();
fnd_76af489a76[0]=new Array();
fnd_76af489a76[1]=new Array();
fnd_76af489a76[1][0]=new Array;
fnd_76af489a76[1][0][0]='nodeid';
fnd_76af489a76[1][0][1]='bob';
fnd_76af489a76[1][1]=new Array;
fnd_76af489a76[1][1][0]='nodename';
fnd_76af489a76[1][1][1]='bob';
fnd_76af489a76[1][2]=new Array;
fnd_76af489a76[1][2][0]='nodedesc';
fnd_76af489a76[1][2][1]='Bob';
fnd_76af489a76[1][3]=new Array;
fnd_76af489a76[1][3][0]='hostname';
fnd_76af489a76[1][3][1]='10.0.10.248';
fnd_76af489a76[1][4]=new Array;
fnd_76af489a76[1][4][0]='nodeenabled';
fnd_76af489a76[1][4][1]='1';
fnd_76af489a76[1][5]=new Array;
fnd_76af489a76[1][5][0]='pingtest';
fnd_76af489a76[1][5][1]='0';
fnd_76af489a76[1][6]=new Array;
fnd_76af489a76[1][6][0]='pingfatal';
fnd_76af489a76[1][6][1]='0';
fnd_76af489a76[1][7]=new Array;
fnd_76af489a76[1][7][0]='alertlevel';
fnd_76af489a76[1][7][1]='0';
fnd_76af489a76[1][8]=new Array;
fnd_76af489a76[1][8][0]='nodeicon';
fnd_76af489a76[1][8][1]='';
fnd_76af489a76[1][9]=new Array;
fnd_76af489a76[1][9][0]='weight';
fnd_76af489a76[1][9][1]='11';
fnd_76af489a76[1][10]=new Array;
fnd_76af489a76[1][10][0]='nodealert';
fnd_76af489a76[1][10][1]='0';
fnd_76af489a76[1][11]=new Array;
fnd_76af489a76[1][11][0]='scheduleid';
fnd_76af489a76[1][11][1]='0';
fnd_76af489a76[1][12]=new Array;
fnd_76af489a76[1][12][0]='name';
fnd_76af489a76[1][12][1]='bob';
fnd_76af489a76[1][13]=new Array;
fnd_76af489a76[1][13][0]='alerttext';
fnd_76af489a76[1][13][1]='Passed';
And if say callback=DataHandler was set then the line:
DataHandler(fnd_76af489a76);
would also be added
Yes I know it's messy but with JS limitations on array index-by-name and pass by reference etc then I'm not quite sure what else to do in order to implement callback etc (using some sort of AJAX thing would be ok but of course that could then just use the XML interface for data).
Examples
I have done some example scripts that do little else than output the data using PHP (for the XML one) and show some very simple evaluation (JS).
XML: http://www.purplepixie.org/freenats/dev ... /?type=xml (save into a .php file)
JavaScript: http://www.purplepixie.org/freenats/dev ... s/?type=js (save into a .html file)
And so...
Unless any major problems are discovered or someone points out a much better way then this form can be settled on and a few more query types (such as node drill down which shows node member tests) can be added.
At some point I would probably do some better examples. The JS possibility is to output a specific class rather than array objects but I don't want to complicate it too much and also ideally keep the XML and JS outputs as similar as possible in structure.
Of course anyone is very welcome to contribute some cool interface examples/classes which people can use with the data. I was toying with the idea of something like a google maps mashup for geo-visibility of nodes etc (though decided I was far too busy failing to develop core functionality and watching 24 to get beyond a static mock-up and of course my UI skills suck).
Regards,
Dave.