<< Advanced Topics

Contents

API Query Types >>

XML and JavaScript API

FreeNATS provides an Application Program Interface (API) which allows developers to query certain information from the system either in XML format or as JavaScript arrays.

Queries are passed in a URL-encoded query HTTP/S request to api.php

Security

Security is an important considering as although the API is read-only and designed to be as SQL injection proof as any other portion of the system other information (such as IMAP passwords for a test) may be exposed by someone using the correct functionality of the system but without your permission.

The API security model is similar to that of the graphs. By default only requests authenticated into FreeNATS will be accepted (those presenting the cookies for a valid session).

You can set the variable api.public to 1. At this point there are no authentication requirements for the API and anyone can query it.

The variable api.key can optionally be set to an alphanumeric string. This must then be provided by public (unauthenticated - authenticated users never have to provide an API key) in the request URI as the variable apikey.

However you use this system though if you are using the JavaScript interface then an enterprising "hacker" could always get your key and see raw data through a JavaScript console. XML on a non-user-exposed script is always the recommended method.

API Modes

The API supports two modes (xml for XML and js for JavaScript) which are passed with mode=X in the URI (if no mode is specified XML is assumed).

XML outputs a formatted XML 1.0 document containing the data and various attributes which are not available in JavaScript. The JavaScript output will build an output data array containing all the information (but in a much nastier form).

Queries

A request to the API takes the form of one or more queries with optional parameters. These are passed un the URI as an encoded array with each element numbered individually. The query is passed as query[x]=NAME and any paramaters as param[x]=val&param1[x]=val1&param2[x]=val etc.

For example we may wish to do an "alerts" query and then a "node" query on a node with a nodeid of "fish". In this case the query portion of the URI would be:

query[0]=alerts&query[1]=node&param[1]=fish

JavaScript API Data Object and Callback

If you specify the type as JavaScript the data is written into an array. By default this data object is named fnd_SOMERANDOM but you can specify the name of the object by passing it as the URI variable dataid.

You can also optionally pass the URI variable callback=JAVASCRIPT_FUNCTION_NAME which will cause the script to call that function passing the data object as the only parameter.