AlertSite XML API

Last modified on March 27, 2024

AlertSite offers two types of Application Program Interface (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:

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/[email protected]
    Client-ssl-cipher AES256-SHA
    Client-peer 204.2.244.15: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

Code Description
0 REST function call completed without errors.
1 Invalid or incompatible parameters specified in the XML request. Check the <Message> tag for details.
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.
30

Possible causes:

  • SessionID is either missing, invalid, logged out, or has expired.

  • SessionID does not match the Login.

  • The specified ObjDevice was not found in your account.

40

Possible causes:

  • Wrong or missing login or password.

  • User is locked.

41

Possible causes:

  • Wrong or missing login or password.

  • Wrong XML payload for specified API operation (for example, List Monitors operation called with <Status>...</Status> payload instead of <List>...</List>).

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.
53 Upload of the monitor failed. Monitor name is missing or contains unsupported characters. For example, DéjàClick monitor names cannot contain " and \..
56 AlertSite Service Agreement has not been accepted.
57 Unsupported monitor type for REST API. Make sure your XML request specifies a valid DeviceType.
60 Missing or invalid XML payload.
61 Invalid XML request. Bad path.
62 Missing or invalid login parameters.
63

Possible causes:

  • The XML request has formatting errors. Use an XML validation tool, such as www.xmlvalidation.com, to find where the error is.

  • Login request is missing the Login value.

64 Invalid parameter(s) for element [ELEMENT_NAME]. Error [code] AlertSite.
65 Invalid monitor.
66 Invalid location(s).
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 <Message> tag for details.

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.

See Also

Example of AlertSite XML API Using Perl

Highlight search results