REST API

AlertSite offers two types of Application Program Interface (API):

  • Report API
  • Device Monitoring API

These APIs enable the user to generate reports and retrieve device information without accessing AlertSite's web interface. A fair amount of programming knowledge is required to use either API, however, the device monitoring API (based on the REST protocol) detailed in this guide requires more technical expertise to use than the Report API described in the Report API help page.

Please read this entire document to become familiar with REST API before attempting to utilize 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 XML format. The following API functions are available:

  1. Login
  2. Logout
  3. List Devices
  4. Edit Device
  5. Add Device
  6. Get Device (Download)
  7. Delete Device
  8. Get Device Status
  9. Get Device 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 a Get Device function, a List Devices request must be issued first in order to retrieve the device number.

The REST API has access to data for Site Devices, DéjàClick Transactions, and API Transactions, but not ServerAgent or Security data.

DéjàClick Transactions must be uploaded through the DéjàClick client. To add DéjàClick to your Firefox browser, go to the DéjàClick Home Page and download from either Mozilla Firefox Add-ons or directly from the DéjàClick Downloads page.

soapUI API Transactions must be created using soapUI from SmartBear. Please go to the API Monitoring help screen for more information, including instructions for adding and managing API devices.

ServerAgent and Security devices must be added through the AlertSite Console.

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 the 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 device types and will be blank.

Each API function will include a Request Header and Response Header:

Example HTTP Header on Login Request only:

User-Agent: AlertSite REST Client/1.0
Content-Type: text/xml

Example 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

Example 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/emailAddress=premium-server@thawte.com
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

Back to top

LOGIN

To call any of the API functions, the first call needs to be Login. This is done by sending a request to the REST server with the AlertSite account username and password (bob and mypass in the example below) embedded in XML. The XML response will indicate if it was a successful or failed login attempt. It is required to make a Login request only once. All subsequent API calls within the script can then be made without additional Login requests.

Path: user/login

Request Body XML:

<Login> <Login>bob</Login> <Password>mypass</Password> </Login> 

Response Body XML:

<Response> 
   <Status>0</Status> 
   <Message>No errors.</Message> 
   <SessionID>a0c54cd5628ea899</SessionID> 
   <ObjDevice></ObjDevice> 
   <ObjCust>24567</ObjCust> 
   <Custid>C34567</Custid> 
   <Company>WidgetWorld</Company> 
   <CurrPlan></CurrPlan> 
   <CurrInterval></CurrInterval> 
   <AvailablePlans>DEJAURL15:2:1,DEJAURL30:1:1,DEJAURL5:3:2</AvailablePlans> 
   <TxnOut></TxnOut> 
</Response> 

As for any of the XML responses to any of the other API calls, there will always be a <Status> and <Message> tag present in the XML. If Status 0 is returned, no errors occurred (such as invalid user, or in the case of adding a new device, insufficient credits). On Status 0, a <SessionID> is given. This is a unique user ID that will be needed to authorize all other function calls. <CurrPlan>, <CurrInterval>, and <AvailablePlans> are not in use for the generalized REST API.

Back to top

LOGOUT

Path: user/logout

Request body XML: none

Response Body XML: none

On the logout step, the REST server will send back a Set-Cookie header that will cause the cookie to expire; thus the customer is logged out.

LIST DEVICES

The LIST API call has two versions. Version 1.0 returns a list of all the customer’s site devices, while Version 1.1 includes enhancements to return all devices and provides for filtering of specific types. In both cases, the first call needs to be to login in order to call any of the API functions (see LOGIN above).

LIST DEVICES V1.0

In the example below, the two site devices in the test account are returned.

Path: devices/list

Request Body XML:

<List> 
   <TxnHeader> 
      <Request> 
         <Login>_LOGIN_</Login> 
         <SessionID>_SESSION_</SessionID> 
      </Request> 
   </TxnHeader> 
   <Source>REST_Client</Source> 
</List> 

Response Body XML:

<Response> 
   <Status>0</Status> 
   <Message>No errors.</Message> 
   <SessionID>6f982ef01eb1f628</SessionID> 
   <ObjDevice>48423</ObjDevice> 
   <ObjCust>24567</ObjCust> 
   <Custid>C34567</Custid> 
   <Company>WidgetWorld</Company> 
   <CurrPlan></CurrPlan> 
   <CurrInterval></CurrInterval> 
   <AvailablePlans>WTP5-1.5x:1:1</AvailablePlans> 
   <TxnList> 
      <Txn> 
      <TxnName>Device 1</TxnName> 
      <TxnDetail
         BillPlan="PPRO15"
         Interval="15"
         MaxSteps="0"
         Monitor="n"
         Notify="n"
         ObjDevice="20829"
         PingError="y"
         TimeOut="30"
         TraceError="n"
         /> 
      </Txn> 
      <Txn> 
      <TxnName>Device 2</TxnName> 
      <TxnDetail 
         BillPlan="PPRO5"
         Interval="5"
         MaxSteps="0"
         Monitor="n"
         Notify="n"
         ObjDevice="14981"
         PingError="y"
         TimeOut="30"
         TraceError="n"
         /> 
      </Txn> 
   </TxnList> 
   <TxnOut></TxnOut> 
</Response>

Back to top

LIST DEVICES V1.1

Version 1.1 of the AlertSite REST API adds the following functionality for LIST:

  • Listing of all device types
  • Filtering of device listing by type

Two new elements can be added to the XML payload to control which device types are to be returned:

<APIVersion> </APIVersion>
<DeviceFilter> </DeviceFilter>

To enable V1.1 functionality, add the following <APIVersion> tag to your <List> command XML as shown below:

<List> 
   <APIVersion>1.1</APIVersion> 
   <TxnHeader> 
      <Request> 
         <Login>my_login</Login> 
         <SessionID>9500832d4c02591d</SessionID> 
     </Request> 
   </TxnHeader> 
   <Source></Source> 
</List> 

The code above will return all site and transaction devices. You can filter the returned list of devices by including the new <DeviceFilter> XML tag. The following example code will deliver only Website type devices:

<List> 
   <APIVersion>1.1</APIVersion> 
   <TxnHeader> 
      <Request> 
         <Login>_LOGIN_</Login> 
         <SessionID>_SESSION_/SessionID> 
         <DeviceFilter>SITE_HTTP</DeviceFilter> 
     </Request> 
   </TxnHeader> 
   <Source></Source> 
</List> 

Accepted values for <DeviceFilter> are:

DEV_SA for ServerAgent device
DEV_SEC for security device
   
EMAIL_IMAP for e-mail (IMAP) device
EMAIL_POP for e-mail (POP) device
EMAIL_ROUNDTRIP for Round-trip e-mail (POP/SMTP) device
EMAIL_SMTP for e-mail (SMTP) device
   
NET_DNS for DNS device
NET_FTP for FTP device
NET_FTPS for FTP over SSL device
NET_PING for Simple Device Ping device
NET_TCP for simple TCP connect device
   
SITE_HTTP for Website device
SITE_SSL for secure Website device
   
TXN_DEJA for DéjàClick transaction
TXN_HTTP for HTTP transaction
TXN_SSL for SSL transaction

Multiple filter types may be submitted as a comma-separated list. The example below returns Secure Website devices, ServerAgent devices, and DéjàClick transactions:

Path: devices/list

Request Body XML:

<List> 
   <APIVersion>1.1</APIVersion> 
   <TxnHeader> 
      <Request> 
         <Login>_LOGIN_</Login> 
         <SessionID>_SESSION_/SessionID> 
         <DeviceFilter>SITE_SSL,DEV_SA,TXN_DEJA</DeviceFilter> 
     </Request> 
   </TxnHeader> 
   <Source>REST_Client</Source> 
</List>

Three devices are returned in the response body: a secure website (SITE_SSL), a ServerAgent device (DEV_SA), and a DéjàClick transaction (TXN_DEJA).

Response Body XML:

<Response> 
   <Status>0</Status> 
   <Message>No errors.</Message> 
   <SessionID>6f982ef01eb1f628</SessionID> 
   <ObjDevice>48423</ObjDevice> 
   <ObjCust>24567</ObjCust> 
   <Custid>C34567</Custid> 
   <Company>WidgetWorld</Company> 
   <CurrPlan></CurrPlan> 
   <CurrInterval></CurrInterval> 
   <AvailablePlans>INSITE-25:1:25,WTPRO5:5:20</AvailablePlans> 

   <TxnList>
      <Txn>
      <TxnName>Secure Web site</TxnName>
      <TxnDetail
         BillPlan="PPRO5"
         Interval="10"
         MaxSteps="0"
         Monitor="y"
         Notify="y"
         ObjDevice="74512"
         PingError="n"
         TimeOut="30"
         TraceError="y"
         />
      </Txn>
      <Txn>
      <TxnName>ServerAgent device</TxnName>
      <TxnDetail
         BillPlan="SA5"
         Interval="5"
         MaxSteps="0"
         Monitor="y"
         Notify="y"
         ObjDevice="54896"
         PingError="n"
         TimeOut="0"
         TraceError="n"
         />
      </Txn>
      <Txn>
      <TxnName>Transaction Test</TxnName>
      <TxnDetail
         BillPlan="DEJAPRO15"
         Interval="15"
         MaxSteps="10"
         Monitor="y"
         Notify="y"
         ObjDevice="70647"
         PingError="n"
         TimeOut="30"
         TraceError="y"
         />
      </Txn>
   </TxnList>
   <TxnOut></TxnOut>
</Response>

Back to top

ADD DEVICE

The client requests to add a site device. A plan credit for the device must be available in the account. If one is not available, Plans-based customers must purchase a plan credit through the AccountPurchase Credits screen in the AlertSite Console (Usage-based customers do not have to make any additional purchases). Note: this command is valid for Site devices only, not DéjàClick, ServerAgent, or Security devices.

The Add Device XML is as follows:

Path: devices/upload

Request Body XML:

<Upload> 
   <TxnHeader> 
      <Request> 
         <Login>_LOGIN_</Login> 
         <SessionID>_SESSION_</SessionID> 
      <TxnHeader> 
         <ObjDevice></ObjDevice> 
         <TxnPlan>_SITEPLAN_</TxnPlan> 
         <TxnDetail
            Caching="n" 
            DeviceType="w"
            Emailaddr="emailaddr.here"
            FullIP="111.222.333.444"
            FullpageTimeOut="30"
            HomeLocation="0"
            HttpFollowRedirect="y"
            HttpMethod="p"
            HttpVersion=”1.0”
            Interval="60"
            IntervalFullpage="60"
            Keyword="abc"
            KeywordInvertMatch="y"
            KeywordType="PlainText"
            Monitor="y"
            MonitorLocations="0"
            MonitorType="I" 
            Notify="n"
            NotifyContent="n"
            Password="qwerty"
            PingError="n"
            POP3addr="pop3addr.here"
            Port='88'
            RealmPassword="some realm password"
            RealmUserId="some realm userid"
            Report302Errors="n"
            Report401Errors="n"
            ResolveDNS="y"
            RR2Enabled="n"
            SMTPaddr="smtpaddr.here"
            SSLCheckCertDate="y"
            TimeOut="30"
            TraceError="n"
            url="www.google.com"
            UserId="john"
            /> 
            <TxnName>Widget Shopping Cart</TxnName> 
         </TxnHeader> 
      </Request> 
   </TxnHeader> 
   <Source>REST_Client</Source> 
</Upload> 

Response Body XML:

<Response> 
   <Status>0</Status> 
   <Message>No errors.</Message> 
   <SessionID>1ae01751673e33eb</SessionID> 
   <ObjDevice>48423</ObjDevice> 
   <ObjCust>24567</ObjCust> 
   <Custid>C34567</Custid> 
   <Company>WidgetWorld</Company> 
   <CurrPlan></CurrPlan> 
   <CurrInterval></CurrInterval> 
   <AvailablePlans>WTP5-1.5x:1:1</AvailablePlans> 
   <TxnOut></TxnOut> 
</Response>

Back to top

EDIT DEVICE

The client requests to edit a Site device. After logging in and retrieving the ObjDevice information using the List Devices call, the Edit Device XML is as follows:

Path: devices/upload

Request Body XML:

<Upload> 
   <TxnHeader> 
      <Request> 
         <Login>_LOGIN_</Login> 
         <SessionID>_SESSION_</SessionID> 
         <TxnHeader> 
            <ObjDevice>_OBJDEVICE_</ObjDevice> 
            <TxnPlan>_SITEPLAN_</TxnPlan> 
            <TxnDetail
               Caching="n" 
               DeviceType="w"
               Emailaddr="emailaddr.here"
               FullIP="111.222.333.444"
               FullpageTimeOut="20"
               HomeLocation="0"
               HttpFollowRedirect="y"
               HttpMethod="p"
               HttpVersion=”1.0”
               Interval="60"
               IntervalFullpage="60"
               Keyword="abc"
               KeywordInvertMatch="y"
               KeywordType="PlainText"
               Monitor="y"
               MonitorLocations="0"
               MonitorType="I" 
               Notify="n"
               NotifyContent="n"
               Password="qwerty"
               PingError="n"
               POP3addr="pop3addr.here"
               Port='88'
               RealmPassword="some realm password"
               RealmUserId="some realm userid"
               Report302Errors="n"
               Report401Errors="n"
               ResolveDNS="y"
               RR2Enabled="n"
               SMTPaddr="smtpaddr.here"
               SSLCheckCertDate="n"
               TimeOut="30"
               TraceError="n"
               url="www.google.com"
               UserId="john"
               /> 
            <TxnName>_DEVICENAME_</TxnName> 
         </TxnHeader> 
      </Request> 
   </TxnHeader>
   <Source>REST_Client</Source> 
</Upload> 

Here the device to edit is specified by the <ObjDevice> tag, whose value is retrieved via the List Device function. In this example, more device parameters have been given than are required in a minimal XML request. These extra parameters are presented here to illustrate instructions for expanded usage of the API. Also note that not all parameters for a device (<TxnDetail>) are valid for all parameter combinations. For instance, POP3addr should be unset (set to “” in its XML tag) if DeviceType is not p.

For the REST API, these are the relevant XML tags of a device (the rest can be excluded in tag <TxnDetail>):

DeviceType
The following device types are available for the API: Web site (w), SMTP (e), POP (p), IMAP (i), Name Server (n), FTP (f), Secure Web site (s)

Interval
This is the monitoring interval, here set to 60 minutes.

Keyword, KeywordType and KeywordInvertMatch
These parameters are only valid for Web site monitoring; i.e., monitoring types w and s.

Monitor
The value of Monitor, should be set to y to enable monitoring for this device.

POP3addr
This is the POP3 address used for a device of monitoring type p.

Port
If port number is not supplied, the default port number will be used for the specified service.

RealmUserId and RealmPassword
These are the variables used when a Web site requires login authentication.

ResolveDNS
To enable DNS to be resolved, this parameter should be set to y.

SMTPaddr
This is the SMTP address used for a device of monitoring type e.

TimeOut
This defines the number of seconds that is allowed for a monitoring until it's determined to be a timed out communication.

url
This is the URL of the Web site to be monitored.

UserId and Password
These parameters are used for POP3 authentication, which corresponds to monitoring type p.

Response Body XML:

<Response>
   <Status>0</Status> 
   <Message>No errors.</Message> 
   <SessionID>1ae01751673e33eb</SessionID> 
   <ObjDevice>48423</ObjDevice> 
   <ObjCust>24567</ObjCust> 
   <Custid>C34567</Custid> 
   <Company>WidgetWorld</Company> 
   <CurrPlan></CurrPlan> 
   <CurrInterval></CurrInterval> 
   <AvailablePlans>WTP5-1.5x:1:1</AvailablePlans> 
   <TxnOut></TxnOut> 
</Response>

Back to top

GET DEVICE (DOWNLOAD)

The client request to retrieve site device specifics after logging in is as follows:

Path: devices/download

Request Body XML:

<Download> 
   <TxnHeader> 
      <Request> 
         <Login>_LOGIN_</Login> 
         <SessionID>_SESSION_</SessionID> 
         <ObjCust>_OBJCUST_</ObjCust> 
         <ObjDevice>_OBJDEVICE_</ObjDevice> 
      </Request> 
   </TxnHeader> 
   <Source>REST_Client</Source> 
</Download> 

Response XML:

<Response> 
   <Status>0</Status> 
   <Message>No errors.</Message> 
   <SessionID>a1077ff0b1a40a62</SessionID> 
   <ObjDevice>48423</ObjDevice> 
   <ObjCust>24567</ObjCust> 
   <Custid>C34567</Custid> 
   <Company>WidgetWorld</Company> 
   <CurrPlan>PPRO5</CurrPlan> 
   <CurrInterval>60</CurrInterval> 
   <AvailablePlans></AvailablePlans> 
   <Device> 
      <Descrip>Widget Test [2008-02-01 16:47:57]</Descrip> 
      <SSLCheckCertDates>Disabled</SSLCheckCertDates> 
      <SSLClientCertRequired>0</SSLClientCertRequired> 
      <SSLVersion></SSLVersion> 
      <LastStatus>0</LastStatus> 
      <DtLastStatus>0000-00-00 00:00:00</DtLastStatus> 
      <DtLastError>0000-00-00 00:00:00</DtLastError> 
      <DtLastErrorCleared>0000-00-00 00:00:00</DtLastErrorCleared> 
      <DtLastNotify>0000-00-00 00:00:00</DtLastNotify> 
      <RealmUserId>some realm userid</RealmUserId> 
      <RealmPassword>xuLJ+Z1umvvd0AeLZo9gV38wNkVlsc4RCGbmiBUuqM=</RealmPassword> 
      <FullIP>111.222.333.444</FullIP> 
      <MonitorTimeout>30</MonitorTimeout> 
      <SMTPaddr>smtpaddr.here</SMTPaddr> 
      <Emailaddr>emailaddr.here</Emailaddr> 
      <POP3addr>pop3addr.here</POP3addr> 
      <FullpageNotify></FullpageNotify> 
      <Report401Errors>1</Report401Errors> 
      <Report302Errors>1</Report302Errors> 
      <RawHttpHeaders>Disabled</RawHttpHeaders> 
      <HttpMethod>p</HttpMethod>
      <HttpVersion>1.0</HttpVersion>
      <url>www.google.com</url> 
      <TxnXml></TxnXml> 
      <TxnPassword></TxnPassword>
      <Keyword>abc</Keyword> 
      <KeywordType>Plain Text</KeywordType> 
      <KeywordInvertMatch>abc</KeywordInvertMatch> 
      <FullpageDynamic></FullpageDynamic> 
      <FullpageChecksize></FullpageChecksize> 
      <FullpageTimeout>20</FullpageTimeout> 
      <CaptureMType>image/jpeg</CaptureMType> 
      <CaptureGroup>img,src,hdr</CaptureGroup> 
      <CaptureLevel>0</CaptureLevel> 
      <Port>88</Port> 
      <ResolveDNS>y</ResolveDNS> 
      <HttpBrowserCode>0</HttpBrowserCode> 
      <Type>w</Type> 
      <Compression>Disabled</Compression> 
      <PingError>n</PingError> 
      <FtpUploadTest>Disabled</FtpUploadTest> 
      <Caching>Disabled</Caching> 
      <PostPairs></PostPairs> 
      <RawPostData>Disabled</RawPostData> 
      <NsLookupObject>0</NsLookupObject> 
      <Notify>n</Notify> 
      <NotifyContent>n</NotifyContent> 
      <NotifyTraceroute></NotifyTraceroute> 
      <HttpFollowRedirect>y</HttpFollowRedirect> 
      <ObjDevlog>0</ObjDevlog> 
      <ObjDevlogPrev>0</ObjDevlogPrev> 
      <HomeLocation>0</HomeLocation> 
      <Monitor>y</Monitor> 
      <MonitorType>I</MonitorType> 
      <MonitorInterval>60</MonitorInterval> 
      <MonitorSeed>59</MonitorSeed> 
      <MonitorLocs>0</MonitorLocs> 
      <MonitorIntervalFullpage>-1</MonitorIntervalFullpage> 
      <IsTxn>0</IsTxn> 
      <TxnMaxSteps>0</TxnMaxSteps> 
      <UpdStamp>2008-02-01 16:48:40</UpdStamp> 
   </Device> 
</Response> 

SSLCheckCertDates
Disabled/Enabled – Enable check for SSL Certification Expiration

SSLClientCertRequired
Should device need a SSL Certificate to connect to remote device

SSLVersion
SSL Version.

LastStatus
Last Status monitored from the device

DtLastStatus
Last Date/Time status taken

DtLastError
Date/Time of Last Error recorded

DtLastErrorCleared
Last Date/Time error cleared

DtLastNotify
Date/Time notified about device

RealmUserId
Realm UserId for authentication

RealmPassword
Realm Password for authentication

FullIP
Resolvable IP address of device

MonitorTimeout
This defines the number of seconds allowed for monitoring before a communication is determined to be timed out.

SMTPaddr
This is the SMTP address used for a device of monitoring type e.

Emailaddr
E-mail address used to send round trip e-mail monitoring

POP3addr
This is the POP3 address used for a device of monitoring type p.

FullpageNotify
To Notify on Fullpage Errors

Report401Errors
Whether a 401 Error should be treated as a device error.

Report302Errors
Whether a 302 Error should be treated as a device error.

RawHttpHeaders
Defines a Raw Header for POST

HttpMethod
GET/POST how Device should be resolved.

HttpVersion
HTTP Version 1.0 or 1.1

url
HTTP Resolvable address of device

TxnXml
N/A

Keyword
Word used to validate correct HTML rendered for Device.
These parameters are only valid for Web site monitoring; i.e., monitoring types w and s.

KeywordType
Keyword Encoding
These parameters are only valid for Web site monitoring; i.e., monitoring types w and s.

KeywordInvertMatch
Reverse Keyword for Matching
These parameters are only valid for Web site monitoring; i.e., monitoring types w and s.

FullpageDynamic
Device Error if missing or new Page Object detected (for Fullpage Devices)

FullpageChecksize
Device Error if Page Object has changed (for Fullpage Devices)

FullpageTimeout
This is the Fullpage Timeout

CaptureMType
N/A

CaptureGroup
N/A

CaptureLevel
N/A

Port
If port number is not supplied, the default port number will be used for the specified service.

ResolveDNS
To enable DNS to be resolved, this parameter should be set to y.

HttpBrowserCode
User Agent string used on Web site devices

Type
The following device types are available for the REST API: Web site (w), SMTP (e), POP (p), IMAP (i), Name Server (n), FTP (f), Secure Web site(s)

Compression
Enabled if Server can accept Gzip payload.

PingError
Use Ping to verify Network Errors

FtpUploadTest
True/false for FTP server. Whether to perform an upload/download test during monitoring

PostPairs
URL Encoded to be used for device in type of POST.

Caching
Use Caching (Repeat Visitor) for HTTP Payload and Objects

RawPostData
Pre-formatted POST data to be used on POST type device

NsLookupObject
Resolve DNS at each monitor interval

Notify
Whether to notify on device error

NotifyContent
Whether to notify on content change

NotifyTraceroute
Traceroute on network error

HttpFollowRedirect
Whether to follow 302 redirection

ObjDevlog
INTERNAL USE ONLY

ObjDevlogPrev
INTERNAL USE ONLY

HomeLocation
Default Location

Monitor
The value of Monitor, should be set to y to enable monitoring for this device.

MonitorType
Only Primary Monitor available through Paesslar API.

MonitorInterval
How often to monitor. Default = 60.

MonitorSeed
INTERNAL USE ONLY

MonitorLocs
INTERNAL USE ONLY

MonitorIntervalFullpage
-1 Indicates Fullpage Disabled; otherwise indicates how often Page Objects should be downloaded from Web Address.

IsTxn
No => 0

TxnMaxSteps
N/A

UpdStamp
Last Date/Time Change of Device

Back to top

DELETE DEVICE

The client request to delete a device after logging in is as follows:

Path: devices/delete

Request Body XML:

<Delete> 
   <TxnHeader> 
      <Request> 
         <Login>_LOGIN_</Login> 
         <SessionID>_SESSION_</SessionID> 
         <ObjCust>_OBJCUST_</ObjCust> 
         <ObjDevice>_OBJDEVICE_</ObjDevice> 
      </Request> 
   </TxnHeader> 
   <Source>REST_Client</Source> 
</Delete> 

Response XML:

<Response> 
   <Status>0</Status> 
   <Message>No errors.</Message> 
   <SessionID>2d472a96369fbaa1</SessionID> 
   <ObjDevice>48423</ObjDevice> 
   <ObjCust>24567</ObjCust> 
   <Custid>C34567</Custid> 
   <Company>WidgetWorld</Company> 
   <CurrPlan></CurrPlan> 
   <CurrInterval></CurrInterval> 
   <AvailablePlans>WTP5-1.5x:1:1</AvailablePlans> 
   <TxnOut></TxnOut> 
</Response>

Back to top

GET DEVICE STATUS

The client requests to list Device Status after logging in. This will return a list of all devices, or, if a value is given in <ObjDevice>, then the status for that one device is returned, along with the most recent status. This is useful to determine if any devices are currently in error.

Path: devices/status

Request Body XML:

<Status> 
   <TxnHeader> 
      <Request> 
         <Login>_LOGIN_</Login> 
         <SessionID>_SESSION_</SessionID> 
         <ObjCust>_OBJCUST_</ObjCust> 
         <ObjDevice>_OBJDEVICE_</ObjDevice> 
      </Request> 
   </TxnHeader> 
   <Source>REST_Client</Source> 
</Status> 

Response Body XML:

<Response> 
   <Status>0</Status> 
   <Message>No errors.</Message> 
   <SessionID>a1077ff0b1a40a62</SessionID> 
   <ObjDevice></ObjDevice> 
   <ObjCust>24567</ObjCust> 
   <Custid>C34567</Custid> 
   <Company>WidgetWorld</Company> 
   <CurrPlan></CurrPlan> 
   <CurrInterval></CurrInterval> 
   <AvailablePlans>WTP5-1.5x:1:1</AvailablePlans> 
   <DeviceStatuses> 
      <Device> 
         <ObjDevice>38525</ObjDevice> 
         <Descrip>Revenue_Home_Page</Descrip> 
         <ObjLocation>10</ObjLocation> 
         <Location>Fort Lauderdale, Florida</Location> 
         <Monitor>y</Monitor> 
         <LastStatus></LastStatus> 
         <DtLastStatus></DtLastStatus> 
         <DtLastError></DtLastError> 
      </Device> 
   </DeviceStatuses> 
</Response> 

ObjDevice
INTERNAL USE ONLY

Location
Location used to Monitor Device

Monitor
y if Device is currently being monitored; otherwise n

LastStatus
Last Status Monitored from Device

DtLastStatus
Last Date/Time Device Monitored

DtLastError
Last Date/Time Device Error Recorded

AvailablePlans
List of Available Plans indicated as <PlanName>:<num_used>:<num_available>

Back to top

GET DEVICE SITE PLANS

The client request to list all configured Site Plans is as follows:

Path: devices/plans

Request Body XML:

<DevicePlans> 
   <TxnHeader> 
      <Request> 
         <Login>_LOGIN_</Login> 
         <SessionID>_SESSION_</SessionID> 
         <ObjCust>_OBJCUST_</ObjCust> 
         <ObjDevice>_OBJDEVICE_</ObjDevice> 
      </Request> 
   </TxnHeader> 
   <Source>REST_Client</Source> 
</DevicePlans> 

Response XML:

<Response> 
   <Status>0</Status> 
   <Message>No errors.</Message> 
   <SessionID>0847b739808e4656</SessionID> 
   <ObjDevice></ObjDevice> 
   <ObjCust>24567</ObjCust> 
   <Custid>C34567</Custid> 
   <Company>WidgetWorld</Company> 
   <CurrPlan></CurrPlan> 
   <CurrInterval></CurrInterval> 
   <AvailablePlans>WTP5-1.5x:1:1</AvailablePlans> 
   <DevicePlans> 
      <Plan> 
         <PlanCode>PPRO5</PlanCode> 
         <PlanName>Performance Professional 5</PlanName> 
      </Plan> 
      <Plan> 
         <PlanCode>EBUS</PlanCode> 
         <PlanName>e-Business</PlanName> 
      </Plan> 
   </DevicePlans> 
</Response> 

AvailablePlans
List of Available Plans marked as <PlanName>:<num_used>:<num_available>

PlanCode
This alphanumeric ID is unique to each plan.

PlanName
This is the plan name.

Back to top

Status Codes

These numerical status codes are returned in the server response within the <Status> tag of the XML tree. The corresponding error message is captured in the <Message> tag of the same XML response. For example, for a successful request, the status code is 0 (within the <Status> tag) and its message will be “No errors” (within the <Message> tag). Below are descriptions for each of the numerical status codes. However, the descriptions listed here are only for the purpose of explanation and they are not the actual embedded text in the <Message> tag.

REST-Specific Status Codes

0 REST function call completed without errors
20 REST API session is invalid
30 REST API session failure
40 Invalid Login Information
51 Unable to resolve IP address

The option to "Resolve DNS" was selected for every test and our DNS servers failed to resolve the site domain name to an IP address.

Device Status Codes

Click HERE for the current list of AlertSite Status Codes.

Back to top

Example of REST API using Perl

The following example illustrates how to get device status information. This entails logging in to the account (Function 1), listing the devices (Function 3), getting the device status information (Function 8), and logging out (Function 2). (Password information has been changed to 'XXXXXX' for display purposes.)

Note that copy-and-paste of this example may introduce hidden characters and break the program, requiring some editing. Also, it is not necessary to use Perl. Any programming language with HTTP/CGI support may be used.

#!/usr/bin/perl

#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!#
#                                                                            #
#               EXAMPLE CODE ONLY - DO NOT COPY-AND-PASTE!                   #
#                                                                            #
#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!#

##############################################################################
# REST client - Login, List Devices, Get Device Status of a specific device  #
#                                                                            #
# NOTE: This is a non-browser REST client, so we need to manually store the  #
# cookie that the server sends back.                                         #
#                                                                            #
# First we login with the existing REST API for Login (via URL /user/login), #
# and we will get a cookie back from the Set-Cookie header.  We also get     #
# back a response XML.                                                       #
##############################################################################

use strict;
use HTTP::Request::Common;
use LWP::UserAgent;

my $REST_SERVER = 'https://www.alertsite.com/restapi';  # Base path
my $LOGIN = 'mylogin@company.com';                      # AlertSite account login
my $PASSWORD = 'mypassword';                            # AlertSite account password

#############################
# Set up User Agent         #
#############################

my $ua = LWP::UserAgent->new;
$ua->agent('AlertSite REST Client/1.0');

my ($POST_XML, $req, $resp, $cookie, $session, $OBJCUST, $DEVICE);

#############################
# 1. Login request          #
#############################

my $POST_XML_LOGIN = << "POST_XML_LOGIN";  # Request body

<Login> <Login>$LOGIN</Login> <Password>$PASSWORD</Password> </Login>

POST_XML_LOGIN

# Set up HTTP request to login.
# Use text/xml and raw POST data to conform to existing REST API

$req = HTTP::Request->new(POST => "$REST_SERVER/user/login");
$req->content_type('text/xml');
$req->content($POST_XML_LOGIN);

print "\n###### LOGIN Request ######\n\n"
.$req->as_string;
print "\n###########################\n";

$resp = $ua->request($req);            # Send request
$cookie = $resp->header('Set-Cookie'); # Save cookie

# Save Session ID and Customer Object ID for subsequent API calls

($session) = $resp->content =~ m|<SessionID>(\w+)</SessionID>|;
($OBJCUST) = $resp->content =~ m|<ObjCust>(\w+)</ObjCust>|;

print "\n###### LOGIN Response (Header and Body) ######\n\n"
.$resp->as_string;
print "##############################################\n";

##############################
# 2. List Devices Request    #
##############################

my $POST_XML = << "POST_XML";             # Request body
<List>
   <TxnHeader>
      <Request>
          <Login>_LOGIN_</Login>
          <SessionID>_SESSION_</SessionID> </Request>
   </TxnHeader>
   <Source></Source>
</List>
POST_XML

# Set Login and Session ID from login request response

$POST_XML =~ s/_LOGIN_/$LOGIN/;
$POST_XML =~ s/_SESSION_/$session/;

# Set up HTTP request to list devices and include the cookie from login.
# Use text/xml and raw POST data to conform to existing REST API.

$req = HTTP::Request->new(POST => "$REST_SERVER/devices/list");
$req->header(Cookie => $cookie);
$req->content_type('text/xml');
$req->content($POST_XML);

print "\n###### LIST DEVICES Request ######\n\n"
.$req->as_string;
print "\n##################################\n";

$resp = $ua->request($req);

print "\n###### LIST DEVICES Response (Header and Body) ######\n\n"
.$resp->as_string;
print "#####################################################\n";

################################
# 3. Get Device Status Request #
################################

#======================================================================#
# For the Get Device Status request, $DEVICE must be set to a specific #
# Device ID.  To get the Device ID of a specific device, do a LIST     #
# DEVICE call with $DEVICE not set, which returns the status of all    #
# devices.  Parse the XML code returned in the output to select the    #
# desired ObjDevice number, and set $DEVICE to that value.             #
#                                                                      #
# In this example, $DEVICE set to 70215 after initial run.             #
#======================================================================#

$DEVICE = 70215;                           # Device ID from List Device run
$POST_XML = << "POST_XML";                 # Request body
<Status>
   <TxnHeader>
      <Request>
          <Login>_LOGIN_</Login>
          <SessionID>_SESSION_</SessionID>
          <ObjCust>_OBJCUST_</ObjCust>
          <ObjDevice>_OBJDEVICE_</ObjDevice>
      </Request>
   </TxnHeader>
   <Source></Source>
</Status>
POST_XML

# Set Login and Session ID from login request response
# Set Customer Object ID and Device ID from list request response

$POST_XML =~ s/_LOGIN_/$LOGIN/;
$POST_XML =~ s/_SESSION_/$session/;
$POST_XML =~ s/_OBJCUST_/$OBJCUST/;
$POST_XML =~ s/_OBJDEVICE_/$DEVICE/;

# Set up HTTP request to list devices and include the cookie from login.
# Use text/xml and raw POST data to conform to existing REST API.

$req = HTTP::Request->new(POST => "$REST_SERVER/devices/status");
$req->header(Cookie => $cookie);
$req->content_type('text/xml');
$req->content($POST_XML);

print "\n###### GET DEVICE STATUS Request ######\n\n"
.$req->as_string;
print "\n#######################################\n";

$resp = $ua->request($req);

print "\n###### GET DEVICE STATUS Response (Header and Body) ######\n\n"
.$resp->as_string;
print "\n##########################################################\n";

Back to top

Output from Execution of REST API Perl Script

Running the above program produces the following output (note: a dummy login and password are used for display purposes):


###### LOGIN Request ######

POST https://www.alertsite.com/restapi/user/login
Content-Type: text/xml

<Login>
   <Login>mylogin@company.com</Login>
   <Password>mypassword</Password>
</Login>

###########################

###### LOGIN Response (Header and Body) ######

HTTP/1.1 200 OK
Connection: close
Date: Wed, 16 Dec 2009 18:42:47 GMT
Server: Apache
Vary: Accept-Encoding,User-Agent
Content-Type: text/xml
Client-Date: Wed, 16 Dec 2009 18:43:12 GMT
Client-Peer: 204.2.244.15:443
Client-Response-Num: 1
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/emailAddress=premium-server@thawte.com
Client-SSL-Cert-Subject: /C=US/ST=Florida/L=Boca Raton/O=Boca Internet Technologies, Inc./CN=www.alertsite.com
Client-SSL-Cipher: DHE-RSA-AES256-SHA
Client-SSL-Warning: Peer certificate not verified
Client-Transfer-Encoding: chunked
Set-Cookie: as_sessionid=z6jypy753rxx6v4um7nnlgofxc6revh4jcoicogrlksgy3erlyyz2xutqx7gsqhfuvwukk5izkp6w;
            domain=.alertsite.com; path=/; secure

<Response>
  <Status>0</Status>
  <Message>No errors.</Message>
  <SessionID>62077a838640ca3f</SessionID>
  <ObjDevice></ObjDevice>
  <ObjCust>35531</ObjCust>
  <ObjParent>57</ObjParent>
  <ObjCust>35531</ObjCust>
  <Login>mylogin@company.com</Login>
  <Custid>C45531</Custid>
  <Company>Widgets R Us</Company>
  <CurrPlan></CurrPlan>
  <CurrInterval></CurrInterval>
  <AvailablePlans>DEJAPRO5:5:10,INSITE-25:1:25</AvailablePlans>



<TxnOut>

</TxnOut>

</Response>


##############################################

###### LIST DEVICES Request ######

POST https://www.alertsite.com/restapi/devices/list
Content-Type: text/xml
Cookie: as_sessionid=z6jypy753rxx6v4um7nnlgofxc6revh4jcoicogrlksgy3erlyyz2xutqx7gsqhfuvwukk5izkp6w;
        domain=.alertsite.com; path=/; secure

<List>
   <TxnHeader>
      <Request>
         <Login>mylogin@company.com</Login>
         <SessionID>62077a838640ca3f</SessionID>
      </Request>
   </TxnHeader>
   <Source></Source>
</List>

##################################

###### LIST DEVICES Response (Header and Body) ######

HTTP/1.1 200 OK
Connection: close
Date: Wed, 16 Dec 2009 18:42:48 GMT
Server: Apache
Vary: Accept-Encoding,User-Agent
Content-Type: text/xml
Client-Date: Wed, 16 Dec 2009 18:43:12 GMT
Client-Peer: 204.2.244.15:443
Client-Response-Num: 1
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/emailAddress=premium-server@thawte.com
Client-SSL-Cert-Subject: /C=US/ST=Florida/L=Boca Raton/O=Boca Internet Technologies, Inc./CN=www.alertsite.com
Client-SSL-Cipher: DHE-RSA-AES256-SHA
Client-SSL-Warning: Peer certificate not verified
Client-Transfer-Encoding: chunked

<Response>
  <Status>0</Status>
  <Message>No errors.</Message>
  <SessionID>62077a838640ca3f</SessionID>
  <ObjDevice></ObjDevice>
  <ObjCust>35531</ObjCust>
  <ObjParent>57</ObjParent>
  <ObjCust>35531</ObjCust>
  <Login>mylogin@company.com</Login>
  <Custid>C45531</Custid>
  <Company>Widgets R Us</Company>
  <CurrPlan></CurrPlan>
  <CurrInterval></CurrInterval>
  <AvailablePlans>INSITE-25:1:25,WTPRO5:5:20</AvailablePlans>

<TxnList>
<Txn>
  <TxnName>InSite%20Test%201%20-%20yahoo</TxnName>
  <TxnDetail Monitor="y" Notify="y" PingError="n" TraceError="y" Interval="5" TimeOut="30" ObjDevice="71277"
             BillPlan="INSITE-25" MaxSteps="25"/>
</Txn>
<Txn>
  <TxnName>InSite%20Test%202%20-%20google</TxnName>
  <TxnDetail Monitor="n" Notify="y" PingError="n" TraceError="y" Interval="5" TimeOut="30" ObjDevice="71278"
             BillPlan="INSITE-25" MaxSteps="25"/>
</Txn>
<Txn>
  <TxnName>InSite%20Test%203%20-%20msnbc</TxnName>
  <TxnDetail Monitor="n" Notify="y" PingError="n" TraceError="y" Interval="5" TimeOut="30" ObjDevice="71279"
             BillPlan="INSITE-25" MaxSteps="25"/>
</Txn>
<Txn>
  <TxnName>InSite%20Test%204%20-%20espn</TxnName>
  <TxnDetail Monitor="n" Notify="y" PingError="n" TraceError="y" Interval="5" TimeOut="30" ObjDevice="71280"
             BillPlan="INSITE-25" MaxSteps="25"/>
</Txn>
<Txn>
  <TxnName>InSite%20Test%205%20-%20cbs</TxnName>
  <TxnDetail Monitor="n" Notify="y" PingError="n" TraceError="y" Interval="5" TimeOut="30" ObjDevice="71281"
             BillPlan="PPRO5" MaxSteps="0"/>
</Txn>
<Txn>
  <TxnName>JB%20-%20Site</TxnName>
  <TxnDetail Monitor="y" Notify="y" PingError="n" TraceError="y" Interval="5" TimeOut="45" ObjDevice="70324"
             BillPlan="INSITE-25" MaxSteps="25"/>
</Txn>
<Txn>
  <TxnName>www.alertsite.com</TxnName>
  <TxnDetail Monitor="n" Notify="n" PingError="n" TraceError="y" Interval="15" TimeOut="20" ObjDevice="69919"
             BillPlan="SLA5" MaxSteps="0"/>
</Txn>
<Txn>
  <TxnName>www.google.com</TxnName>
  <TxnDetail Monitor="n" Notify="y" PingError="n" TraceError="y" Interval="15" TimeOut="20" ObjDevice="70215"
             BillPlan="PPRO5" MaxSteps="0"/>
</Txn>

</TxnList>


<TxnOut>

</TxnOut>

</Response>


#####################################################

###### GET DEVICE STATUS Request ######

POST https://www.alertsite.com/restapi/devices/status
Content-Type: text/xml
Cookie: as_sessionid=z6jypy753rxx6v4um7nnlgofxc6revh4jcoicogrlksgy3erlyyz2xutqx7gsqhfuvwukk5izkp6w;
        domain=.alertsite.com; path=/; secure

<Status>
   <TxnHeader>
      <Request>
          <Login>mylogin@company.com</Login>
          <SessionID>62077a838640ca3f</SessionID>
          <ObjCust>35531</ObjCust>
          <ObjDevice>70215</ObjDevice>
      </Request>
   </TxnHeader>
   <Source>Widgets R Us</Source>
</Status>

#######################################

###### GET DEVICE STATUS Response (Header and Body) ######

HTTP/1.1 200 OK
Connection: close
Date: Wed, 16 Dec 2009 18:42:49 GMT
Server: Apache
Vary: Accept-Encoding,User-Agent
Content-Type: text/xml
Client-Date: Wed, 16 Dec 2009 18:43:14 GMT
Client-Peer: 204.2.244.15:443
Client-Response-Num: 1
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/emailAddress=premium-server@thawte.com
Client-SSL-Cert-Subject: /C=US/ST=Florida/L=Boca Raton/O=Boca Internet Technologies, Inc./CN=www.alertsite.com
Client-SSL-Cipher: DHE-RSA-AES256-SHA
Client-SSL-Warning: Peer certificate not verified
Client-Transfer-Encoding: chunked

<Response>
  <Status>0</Status>
  <Message>No errors.</Message>
  <SessionID>62077a838640ca3f</SessionID>
  <ObjDevice>70215</ObjDevice>
  <ObjCust>35531</ObjCust>
  <Custid>C45531</Custid>
  <Company>Widgets R Us</Company>
  <CurrPlan></CurrPlan>
  <CurrInterval></CurrInterval>
  <AvailablePlans>INSITE-25:1:25,WTPRO5:5:20</AvailablePlans>
  <DeviceStatuses>
    <Device>
    <ObjDevice>70215</ObjDevice>
    <Descrip>www.google.com</Descrip>
    <ObjLocation>20</ObjLocation>
    <Location>Atlanta, Georgia</Location>
    <Monitor>n</Monitor>
    <LastStatusCode>0</LastStatusCode>
    <LastStatus>Site is OK Now!</LastStatus>
    <DtLastStatus>2009-12-15 23:03:03</DtLastStatus>
    <DtLastError></DtLastError>
    <DtLastErrorCleared></DtLastErrorCleared>
  </Device>
  <Device>
    <ObjDevice>70215</ObjDevice>
    <Descrip>www.google.com</Descrip>
    <ObjLocation>72</ObjLocation>
    <Location>Boston, Massachusetts</Location>
    <Monitor>n</Monitor>
    <LastStatusCode>0</LastStatusCode>
    <LastStatus>Site is OK Now!</LastStatus>
    <DtLastStatus>2009-12-15 22:48:04</DtLastStatus>
    <DtLastError></DtLastError>
    <DtLastErrorCleared></DtLastErrorCleared>
  </Device>
  <Device>
    <ObjDevice>70215</ObjDevice>
    <Descrip>www.google.com</Descrip>
    <ObjLocation>52</ObjLocation>
    <Location>Chicago, Illinois - Ubiquity</Location>
    <Monitor>n</Monitor>
    <LastStatusCode>0</LastStatusCode>
    <LastStatus>Site is OK Now!</LastStatus>
    <DtLastStatus>2009-12-15 23:03:03</DtLastStatus>
    <DtLastError></DtLastError>
    <DtLastErrorCleared></DtLastErrorCleared>
  </Device>
 
  </DeviceStatuses>   
</Response>

##########################################################

Back to top

© 2012 by AlertSite a SmartBear Business --
Syndicate this site RSSATOM