AlertSite offers two types of Application Program Interface (API):
- Report API
- Monitoring API
These APIs enable the user to generate reports and retrieve monitor information without accessing AlertSite web interface. A fair amount of programming knowledge is required to use either API, however, the monitoring API (based on the REST protocol) detailed in this guide requires more technical expertise to use than the Report API.
Please read this entire document to become familiar with REST API before using it.
REST API Functions
An API has been developed based on the principles of Representational State Transfer (REST) to allow customers to perform a basic set of actions by sending and receiving data in the XML format. The following API functions are available:
- List Monitors
- Edit Monitor
- Add Monitor
- Get Monitor (Download)
- Delete Monitor
- Get Monitor Status
- Get Monitor Site Plans
|The user must first be logged in for permission to access any of these API functions.|
From a programmatic standpoint, the validation of a user’s credentials is handled by passing a cookie in the HTTP header. The REST client requests a login, the server responds by sending back a Set-Cookie header on successful login, and the client, in turn, uses this same cookie in the HTTP header for each subsequent request.
Some functions require information returned in the response of another request. For example, to do the Get Monitor function, the List Monitors request must be issued first in order to retrieve the monitor number.
The REST API has access to data for site monitors, DéjàClick monitors, and API monitors, but not ServerAgent or Security data.
DéjàClick monitors must be uploaded through the DéjàClick client. You can download AlertSite here.
SoapUI API monitors must be created using ReadyAPI or SoapUI from SmartBear. For more information, see Create API Monitor From SoapUI Test.
ServerAgent and Security monitors. must be added through AlertSite 1.0.
The REST API sends all communication in the form of an XML-formatted text string via a raw POST action. The POST can be done via Ajax, although our example client code does not use Ajax. The essential components of each request are a URL and the XML structure. The URL represents the REST resource and the XML specifies various request and response parameters.
Below is a description of the URLs and XML code for each of the available API calls. The base URL is
https://www.alertsite.com/restapi and must precede the Path shown for the call. For instance, to send a Login request, the full URL would be
https://www.alertsite.com/restapi/user/login. These are production URLs.
Please note that the response may contain XML tags that are not used with all monitor types and will be blank.
Each API function will include a request header and response header:
HTTP Header on Login Request only
User-Agent AlertSite REST Client/1.0 Content-Type text/xml
HTTP Header on All Other Client Requests
User-Agent AlertSite REST Client/1.0 Content-Type text/xml Cookie as_sessionid=5ermggi6zfnkgur34wop2mkm5mzdit7es6hkf6kbdeuwh727tplzodt4uommzygp; domain=.alertsite.com; path=/; secure
- Server Response Header
HTTP/1.1 200 OK Connection close Set-Cookie as_sessionid=5ermggi6zfnkgur34wop2mkm5mzdit7es6hkf6kbdeuwh727tplzodt4uommzygp; domain=.alertsite.com; path=/; secure Date Fri, 20 Feb 2009 15:17:53 GMT Client-SSL-Cert-Issuer /C=ZA/ST=Western Cape/L=Cape Town/O=Thawte Consulting cc/OU=Certification Services Division/CN=Thawte Premium Server CA/emailAddressfirstname.lastname@example.org Client-ssl-cipher AES256-SHA Client-peer 126.96.36.199:443 Client-date Fri, 20 Feb 2009 15:17:56 GMT Client-ssl-warning Peer certificate not verified Content-type text/xml Client-ssl-cert-subject /C=US/ST=Florida/L=Boca Raton/O=Boca Internet Technologies, Inc./CN=www.alertsite.com' Server Apache
REST-specific status codes
|0||REST function call completed without errors.|
Invalid or incompatible parameters specified in the XML request. Check the
|2||Your account does not have enough fullpage credits.|
|3||No credits available for this plan.|
|4||Invalid format of POP3 address.|
|10||User session has expired, please log in again.|
|12||No active user session. Please log in.|
|20||User session is invalid.|
|47||Your account has not been activated yet.|
|48||Your login account has insufficient access to use this feature.|
|49||Login failed. Please try again.|
|51||Unable to resolve IP address.|
Upload of the monitor failed. Monitor name is missing or contains unsupported characters. For example, DéjàClick monitor names cannot contain
|56||AlertSite Service Agreement has not been accepted.|
Unsupported monitor type for REST API. Make sure your XML request specifies a valid
|60||Missing or invalid XML payload.|
|61||Invalid XML request. Bad path.|
|62||Missing or invalid login parameters.|
|64||Invalid parameter(s) for element [ELEMENT_NAME]. Error [code] AlertSite.|
|98||Action not implemented.|
|99||Internal AlertSite error.|
|501||Invalid HTTP Method. Please use HTTP POST.|
|9999||Invalid or incompatible parameters specified in the XML request. Check the
Monitor status codes
API last access time
Admin and Co-Admins can see which users accessed AlertSite APIs and when they did it last on the Manage Users screen.