Introduction

The Awasu API opens up Awasu's functionality to both third-party applications and Awasu extensions, allowing powerful features to be built on top of Awasu's information management engine. In particular, full create/read/update/delete functionality is available for key Awasu features such as channels, reports and workpads, allowing these to be maintained dynamically.

The services offered are grouped into the following categories:

Requests and responses are done over HTTP [1] and by default, Awasu listens for requests on port 2604 [2]. In this documentation, "$" is used to mean "the appropriate URL stem for issuing Awasu API requests" e.g. $/channels/list means http://localhost:2604/channels/list [3].

Libraries are available on GitHub that simplify the process of calling the Awasu API.

Security

By default, a security token must be included in each API call (via the token parameter), to prevent unauthorized access to your Awasu.

Hint
It is possible (but not recommended) to remove the security token so that API calls will not need to specify a token parameter.

Remote access

Awasu API remote access By default, access to the Awasu API is restricted to programs running on the same computer as Awasu. To allow access from other computers, open the Program Options, choose which network interfaces to allow access on and a port number to accept requests on.

Template response files

Most API calls return a response generated from a template file in the Resources/API sub-directory under the Awasu installation directory. The filename is usually derived from the name of the API call e.g. $/channels/list will look for a template file starting with channels-list.

The file extension is taken from the format parameter. Response template files for XML and JSON are supplied by default but new formats can be added by creating a new response template file with the appropriate extension, and then specifying that extension in the API call e.g. $/reports/list?format=txt will return a response generated from a file called reports-list.txt.

API parameters

All API calls take parameters, specified in the usual way as part of the HTTP request (key=val pairs in the URL). It is also possible to submit requests using an HTTP POST request, and specifying parameters in the POST data, as attributes of an <apiArgs> node, and/or key/value pairs in the node's CDATA. For example,

GET buildInfo?f=html&token=xyz
is equivalent to
POST buildInfo
<apiArgs f="html"> token=xyz </apiArgs>
This is the recommended way of submitting requests if you are using an API token.

Standard parameters

All API calls recognize the standard parameters described below.

tokenAPI token.
If a token has been set in the Program Options, it must be specified in each API call.
format (f)Format to return the results in (usually xml or json).
For API calls that return a response generated from a template file, this parameter is used to determine which template file to use (see above).

The default format is usually xml.
responseTemplate (rt)Response template filename.
For API calls that return a response generated from a template file, this parameter is used to determine which template file to use (see above).
silentFlags if a silent response (HTTP 204) should be returned.
A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.