AlertSite JSON API

AlertSite offers two APIs to manage monitors: JSON API and XML API, each has its own capabilities and syntax. This document describes the JSON API. Documentation for the XML API is available at http://help.alertsite.com/RestAPI.

 

AlertSite JSON API is a RESTful web service that allows you to manage monitors programmatically by sending and receiving JSON data to/from the AlertSite server. You can use the API to:

The API supports all monitor types available in both AlertSite UXM and AlertSite 1.0.

You can access the API using any programming language or tool that supports making HTTP requests and parsing JSON responses.

Contents

Endpoint

The base URL for all API requests is:

https://www.alertsite.com/alertsite-restapi

For example, POST /login means a POST request to https://www.alertsite.com/alertsite-restapi/login.

All requests are sent over a secure HTTPS connection.

JSON Format

AlertSite REST API uses JSON as the data format for requests and responses. Requests containing a body (POST and PATCH) must include the Content-Type header:

Content-Type: application/json

Operations

AlertSite REST API provides the following operations:

Operation Description
Login Generates the session ID used to authenticate other API calls.
Get Monitors Returns the configuration information for one, several or all monitors.
Get Locations Returns information about all available monitoring locations, including private nodes.
Add Monitor Creates a new monitor. Supports uploading of DéjàClick scripts, Selenium scripts and SoapUI projects.
Edit Monitor Updates the monitor configuration, for example, monitoring locations, run interval, enabled or disabled status.
Delete Monitor Deletes a monitor specified by ID.

Note that the Add Monitor, Edit Monitor and Delete Monitor operations must be performed using an Admin or Co-Admin user account.

Authentication

The first API call needs to be Login. It returns a session ID:

{
  "metadata" : {
    "login" : "demo@example.com",
    "session" : "ef770427109e343e",
    "status" : "0",
    "message" : "No errors."
  }
}

This session ID is then used to authenticate other API calls.

There are two ways to authenticate requests:

Using Authorization Header (Recommended)

Authentication is done by adding the following header to all requests:

Authorization: Bearer BEARER_TOKEN

BEARER_TOKEN is a base64-encoded string login:sessionId. For example, if your login is demo@example.com and the session ID is ef770427109e343e, you need to Base64-encode the string demo@example.com:ef770427109e343e, which gives you ZGVtb0BleGFtcGxlLmNvbTplZjc3MDQyNzEwOWUzNDNl. The final header will be:

Authorization: Bearer ZGVtb0BleGFtcGxlLmNvbTplZjc3MDQyNzEwOWUzNDNl

Pseudocode to calculate the bearer token and add the Authorization header looks like:

request.addHeader("Authorization", "Bearer " + encode_base64(login + ":" + session))

Using Query Parameters

Another way to authenticate API calls is to pass the login and session ID as part of the request query string:

PATCH /devices/1234?login=demo%40example.com&session=ef770427109e343e

Note that the email needs to be URL-encoded, for example, @ is converted to %40. Many programming languages provide a method to do this.

This approach is the most suitable for testing API calls using cURL, wget, SoapUI, or similar tools. For production code, we recommend using the Authorization header.

Session ID Expiration

Session IDs returned by the Login operation expire after 15 minutes, but get refreshed with each API call. So, the session expires 15 minutes after your last API call. After that any API call that requires authentication will return a session error. In this case, you will need to call Login again to get a new session ID for authentication.

Monitor IDs

Some REST API operations require a numeric monitor ID. You can get a list of all your monitor IDs using the Get Monitors operation. You can also see monitor IDs in AlertSite – open the monitor settings and examine the browser address bar.

AlertSite UXM:

Monitor ID in AlertSite UXM

AlertSite 1.0:

Monitor ID in AlertSite 1.0

Errors

API responses include metadata with the status and message fields. Status 0 and message "No errors" indicate a successful request. Any other statuses indicate an error. For example:

{
  "metadata": {
    "login": "demo@example.com",
    "status": "40",
    "message": "Invalid login information."
  }
}

Possible errors and reasons are listed below.

Code Message Comments
0 No errors.  
20 Session is invalid. Possible reasons:
  • The request authentication information is missing, incomplete or incorrect.
  • The session ID is incorrect or has expired. Call Login again to get a new session ID for subsequent API calls.
30 Session failure. The session ID is incorrect or has expired. Call Login again to get a new session ID for subsequent API calls.
40 Invalid login information. Possible reasons:
  • Incorrect login or password specified in the Login operation.
  • The request authentication information is missing or incorrect. For example, session ID does not match the login.
  • The user is locked.
41 Invalid user information.  
47 Your account has not yet been activated.  
48 Your login account has insufficient access to use this feature. The operation requires an Admin or Co-Admin user account, but was called using a read-only or report-only account.
56 Service Agreement has not been accepted. The specified user account has never logged into AlertSite before. Log in to AlertSite manually in your browser and accept the Service Agreement.
60 Missing or invalid data.  
61 Invalid request. Bad path. Request URL is incorrect or misspelled.
62 Missing or invalid login parameters. The login or password (or both) is not specified in the Login operation.
63 Malformed JSON request. POST and PATCH requests return this error if:
  • JSON in the request body contains syntax errors, such as misplaced quotes, missing commas or duplicate fields. Use www.jslint.com to check your JSON syntax.
  • Request body is missing.
64 Invalid parameter. Error [code] AlertSite. Common reasons for this error are:
  • A required parameter is missing, misspelled or has an incorrect value. For example, billing_plancode should be in the format UBM - A/A and not UBM - A/A:1:50.
  • Incompatible parameters are specified. For example, Round Robin monitoring mode ("mode": "R") with just 1 location instead of 2+ locations.
  • You are trying to create a monitor using the billing_plancode that does not support this monitor type. Check which plan is used by your existing monitors and use the same plan code.
  • You are trying to edit a Perfecto monitor. These monitors cannot be created and edited via the API.
  • The script value (contents of a DéjàClick, Selenium or SoapUI file to upload) is encoded incorrectly. For more information on the format of the script value, see Uploading DéjàClick, Selenium and SoapUI Files.

 

Transaction requires between 1 and [max] steps, but you have 0

This error can occur if the specified test_suite or test_case was not found in the SoapUI project. Double-check the test suite and test case names.

 

No credits available for this plan

You have reached the monitor limit for the specified billing_plancode. No more monitors can be created using this plan.

 

Feature not available with this plan

The request body specifies a monitor parameter that is not supported by your AlertSite plan. If the error mentions a parameter not included in the request, this means that the default value of this parameter is not supported by your plan. Check the monitor configuration in AlertSite 1.0 to see which parameters and values are supported by your AlertSite plan.

To avoid the error, change the request body to use a different value for the problematic parameter. For example, if the error says:

Feature not available with this plan. ... (Follow Redirection? = YES)

set the Follow Redirection parameter to No:

"http_follow_redirects": "n"
65 Invalid device. Possible reasons:
  • The specified monitor ID was not found in your AlertSite account.
  • The request URL for the Edit Monitor or Delete Monitor operation is missing the monitor ID. The URL should be:

    https://www.alertsite.com/alertsite-restapi/devices/1234

    (with 1234 replaced by your monitor ID)

66 Invalid location(s). Possible reasons:
  • Request body contains an incorrect location ID. See here for a list of AlertSite’s global location IDs. If you use private nodes, use the Get Locations operation to get all your location IDs.
  • Request body specifies locations but is missing home_location.
99 Internal CGI error.  
501 Invalid HTTP Method. Allowed values are [method names] For example, the request that should be made via POST was made via GET.

Limitations

Monitor Types

Perfecto monitors cannot be created or edited through the API, but they can be listed by the Get Monitors operation.

Monitor Settings

The API provides access to just a subset of monitor configuration settings. Supported settings are listed in Monitor Data Fields. The following settings cannot be read or changed through the API.

Common settings:

Web URL monitors:

DéjàClick monitor settings:

Selenium monitor settings:

API endpoint monitors:

Secure Web URL, Secure API endpoint and SoapUI monitor settings:

Code Examples

This documentation includes code examples in Python and cURL that can be found in the Examples section in individual operation descriptions.

Python examples use the Requests library.

cURL is a command-line tool that allows you to make API calls from command line (Windows command prompt, OS X terminal or Linux shell) without having to write programming code. cURL is preinstalled on macOS and on many Linux systems. Windows users can download cURL from this web site:

See Also

© 2017 SmartBear Software. All rights reserved.      Terms of Use · Privacy Policy