This topic describes the configuration settings for API endpoint monitors. These monitors make an HTTP request (GET, POST, PUT, PATCH, HEAD, or DELETE) to the specified URL, and track the status (OK or error) and response time. You can also customize the monitoring interval, timeout, locations and other settings described below.
We recommend that you create and edit API endpoint monitors in AlertSite UXM – it offers a handy interface to specify the request body and headers.
Click the image to enlarge it.
Notes:
-
You must be an Admin, Co-Admin, or Power User to change the monitor settings.
-
It may take a few minutes for the changes to take effect.
-
You can set the default settings for new monitors in > Settings > Preferences > Monitor Defaults in AlertSite UXM, or in Account > Manage Account in AlertSite 1.0.
Common
Test on Demand
Runs a test on demand from the monitor’s primary location. Unlike Validate, test results are based on the response HTTP status, response time and on the presence or absence of the specified keyword in the response.
| Note: | The results of tests on demand are not included in your monitor run history, do not trigger alerts and do not affect your SLA metrics. |
Download Project
Click this button to download the SoapUI project that AlertSite generated for this monitor. You can run this project locally in SoapUI or ReadyAPI.
| Note: | To access the download button in AlertSite 1.0, click Manage API Project in the top row of buttons. |
Endpoint
Request Method (or HTTP Method in AlertSite 1.0)
The HTTP method for the request: GET (default), POST, HEAD, PUT, DELETE, or PATCH.
URL
The request URL, including http:// or https://. For example:
http://example.com
https://www.example.com/login
http://example.com:8089/reports/usage?rdate=LastWeek&format=json
If the URL needs query parameters, you can append them to the URL or enter them in the Parameters table.
Note: Multiple query string parameters with the same name are not supported (such as http://example.com/users?role=user&role=admin). This is a limitation of SoapUI, which AlertSite uses to run API monitors.
Validate Step (AlertSite UXM only)
Click this button to send a sample request and view the response. This way, you can verify that the request URL, headers, and body are correct.
Request
Headers (AlertSite UXM only)
Request headers, such as Accept, Authorization, API keys, and so on.
| Tip: | To configure the Authorization header for Basic or Bearer authentication, use the Authentication tab instead. |
Parameters (AlertSite UXM only)
Query parameters appended to the request URL. The table is prepopulated with the existing parameters specified in the URL. See Parameters for details.
| Note: | Query parameters must have unique names. |
Body
Specify a request body for the POST, PATCH, or PUT requests.
Content Type (AlertSite UXM only)
POST, PATCH and PUT requests may include a request body. If you are sending a body, use this option to specify the body content type, such as JSON or XML. This determines the Content-Type header that will be included in the request.
To use a different content type, select Custom and enter a value for the Content-Type header in the Headers table.
Content Body (AlertSite UXM only)
An optional body to send with the POST, PATCH or PUT request. The body can be JSON, XML, or any other text data. For example:
{
"id": 5,
"username": "trillian",
"is_admin": true
}
Web Form (AlertSite UXM only)
This option is available only for POST requests and is only useful if you need to send form data (application/x-www-form-urlencoded).
Selecting this option switches to the form edit mode, where you can enter form fields and values one per line, like this:
name=Bob
[email protected]
company=ABC Corp
The request will be sent with Content-Type: application/x-www-form-urlencoded, and the request body will be formatted appropriately.
| Note: | The Web Form mode does not support custom headers. |
If Web Form is unselected, you need to format the form data in the Content Body manually. The key=value pairs must appear on one line, separated by the ampersand (&), and the values must be percent-encoded. For example, spaces in the values must be replaced with %20, @ - with %40, and so on:
name=Bob&email=bob%40example.com&company=ABC%20Corp
Authentication
API endpoint monitors provide options for Basic and Bearer authentication.
Basic authentication
Simple authentication using the specified Username and Password, suitable for APIs that expect the Authorization header in the format:
Authorization: Basic base64(username:password)
If the server returns an error even if the username and password are correct, try selecting this option. This will send the Authorization header in the initial request, bypassing the standard Basic authentication flow. Some servers require preemptive Basic authentication and will not authenticate otherwise.
With this option unselected, AlertSite follows the standard Basic authentication flow:
-
AlertSite sends the initial request without the
Authorizationheader. -
The server responds with the 401 “Unauthorized” response code, indicating that it requires a username and password.
-
AlertSite repeats the request with the
Authorizationheader containing the credentials.
Bearer authentication
The specified Token will be sent in the Authorization header as follows:
Authorization: Bearer TOKEN
Do not include the Bearer prefix in the token, it will be added automatically.
Response
Body and Headers
The response headers and body received from the server. If you change the request configuration (such as URL or parameters), click Validate to retest and see a new response.
Assertions
Assertions used to verify the response body. Click to the right of the table to add new assertions.
Each assertion has the form:
source property operator value
For example:
JSON Response book[0].title equals The Lord of the Rings
To learn more about configuring assertions, see API Assertions.
Main
Name (or Site Name in AlertSite 1.0)
The monitor name that appears in dashboards and reports. For example, Customer Login.
Monitor ID (in AlertSite UXM)
Read-only. The monitor ID that can be used in AlertSite APIs.
Enable Monitoring (or Monitoring Is in AlertSite 1.0)
AlertSite UXM
On the Main tab, select or clear the Enable Monitoring check box to enable or disable monitoring.
AlertSite 1.0
Set Monitoring Is to Enabled to enable the monitor or Disabled to disable it.
Monitor ID (in AlertSite UXM)
Read-only. The monitor ID that can be used in AlertSite APIs.
Name (or Site Name in AlertSite 1.0)
The monitor name that appears in dashboards and reports. For example, Customer Login.
Enable alerting
AlertSite UXM
Enable availability or performance alerts on the Alerts tab.
AlertSite 1.0
Set Notify on Error to Yes to enable availability alerts for this monitor or No to disable availability alerts. Performance alerts are configured separately by clicking the Performance Alerts button in the top row.
Measurement Plan (or Site Plan in AlertSite 1.0)
The monitoring plan used for this monitor.
Run Interval (Minutes) (or Check Every in AlertSite 1.0)
How often the monitor runs. Possible values depend on the Measurement Plan selected for this monitor.
The maximum acceptable response time for each monitor step (for HTTP requests). The default value is 30 seconds. It can be changed in individual steps by using the Timeout assertion. Longer response time will trigger error 6570, and the monitor run will be stopped.
| Note: | The step timeout is not a connection timeout. The response is downloaded, and then the measured response time is compared against this limit. |
Monitoring Mode (or Monitoring Type in AlertSite 1.0)
The monitoring mode controls if locations check your API endpoint simultaneously or sequentially, and when they send alerts. See Monitoring Modes for possible values and details.
Rotate Locations
For each monitor, you define a location pool. Rotation means the monitor uses a subset of this location pool (say, 2 out of 10 locations) on every run, cycling through the locations. If rotation is not used, the monitor checks from all of its locations every time.
Notes:
-
Rotated locations are not available for monitors that use private locations.
-
Usage-Based Monitoring plan allows rotated locations for the following monitoring modes: Round Robin, SLA (MultiPOP), Global Notify, and Global Verify.
-
Legacy plans (Performance Pro, SLA) support rotating through locations only for the Round Robin and SLA (MultiPOP) modes.
Locations Per Run (or Locations per Interval in AlertSite 1.0)
If Rotate Locations is selected, you need to specify the number (subset) of locations to use for each monitor run. This value ranges from 1 to the total number of locations you selected for the monitor.
When using the Round Robin or SLA (MultiPOP) monitoring mode, you need at least 2 locations per interval.
Enable Local Retry (or Disable Local Retry in AlertSite 1.0)
Applies only to monitors using the Usage-Based Monitoring plan. If local retry is enabled, then whenever the monitor finds an error, it will repeat the test from the same location to see if the problem is temporary. If the retry succeeds, no alert is triggered. For more information, see Local Retry and Global Verification.
| Note: | The retry consumes extra measurement credits. |
Enable AlertSite QA Testing (or Disallow AlertSite QA Testing in AlertSite 1.0)
Before releasing AlertSite updates, SmartBear runs regression tests to make sure that both existing and new functionality work correctly. Select (or clear in AlertSite 1.0) this check box to include your monitor in SmartBear regression testing, so we can make sure your monitors will work correctly after AlertSite updates. Participation is voluntary.
Active Locations
Select one or more locations to monitor you API from. For details, see Selecting Locations for Monitoring.
Advanced
Monitoring
Playback Engine
The engine used to run the monitor at AlertSite’s global monitoring locations. The playback engine defines which functionality a monitor can use, such as the supported syntax for JSON assertions. We recommend that you create monitors using the same version of ReadyAPI as the playback engine you will use.
Possible values:
-
Default – the default engine is TestEngine 1.7
-
ReadyAPI 1.9
-
TestEngine – same as TestEngine 1.7
-
TestEngine 1.7 – functionally corresponds to ReadyAPI 2.8
-
TestEngine 1.23 – functionally corresponds to ReadyAPI 3.8
Notes:
-
If TestEngine 1.23 is selected but is not available at a location, TestEngine 1.7 is used instead.
-
Private Node Server locations ignore this option and use the locally available engine.
Monitor Note (or Device Note in AlertSite 1.0)
Leave a note for yourself or other users. Note text can be up to 1000 characters long. This note will appear on the AlertSite Dashboard when you hover over the icon. The note can also be included in alerts.
Monitor Sharing
SSL Options
These options only apply to monitors that test https:// (secure) URLs.
SSL Version
Optional. The security protocol to use to connect to the server. Use it only if your server requires a specific SSL or TLS version. Otherwise leave it blank, and the monitor and server will select a protocol automatically.
SSL Certificate
If a client SSL certificate or keystore is required to access your monitored API, upload this certificate or keystore to AlertSite and then select it from the list. The certificate will be automatically installed to AlertSite global locations selected for this monitor. For details, see Using SSL Certificates and Java Keystores.
| Note: | Private locations (Private Node Server and InSite) support client-side SSL certificates starting from v. 2.1.2. To install client-side certificates on earlier versions of Private Node Server, please contact Support. |
HTTP Options
These options specify how steps without Status Code assertions handle HTTP status codes 301, 302, 401 and 403.
Report Redirects as Errors (HTTP 301/302) (or Report Redirects (HTTP 301/302) as Errors in AlertSite 1.0)
By default, if the API response has HTTP status 301 or 302 (meaning a redirect), AlertSite repeats the request to the URL specified in the response header Location. Selecting this option prevents the monitor from following redirects, and response statuses 301 and 302 will be considered errors.
| Note: | The Status Code assertion can be used to override successful and error statuses for individual steps. |
Report Authentication Challenges as Errors (HTTP 401/403) (or Authentication Challenges (HTTP 401/403) as Errors in AlertSite 1.0)
If this option is selected, the monitor will raise an error if the final status code we receive from your API is HTTP 401 or 403, indicating an authentication error.
Notes:
-
If your API requires Basic authentication, you can specify the username and password on the Authentication tab in the request configuration.
-
The Status Code assertion can be used to override successful and error statuses for individual steps.
Capture
Capture Level
AlertSite runs API endpoint monitors using SoapUI. This option specifies whether to store SoapUI logs from the test runs. SoapUI logs include complete requests and responses (URL, headers, body, HTTP status code) and the details of any errors that may have occurred.
Select the level of logs to store:
-
Disabled – Do not store SoapUI test logs.
-
Error Only – (Default) Store SoapUI logs only for failed monitor runs.
-
All Steps – Always store SoapUI log, even for successful runs. This option is available only on Usage-Based Monitoring accounts only, and consumes 0.5 measurement credits per capture.
You can view SoapUI logs:
-
On the Monitor Runs dashboard, by using the Run Log and (step log) buttons in expanded results.
-
In the Detail report by clicking the
camera icon.
You can also have the SoapUI log attached to email alerts if you configure alert recipients with the Attach server response to e-mail alerts option. This does not depend on the monitor’s Capture Level.
Transaction Trace
This option enables or disables AppDynamics transaction tracing for the monitor (see AppDynamics Integration). If it is selected, AppDynamics captures transaction snapshots for HTTP requests made by the monitor. The snapshots contain server-side performance details, such as the slowest code methods and SQL queries. You can access these snapshots from the Monitor Runs dashboard.
Custom Properties
Custom Properties
This section shows custom properties defined for your monitor. You can select a value for each property from the predefined list.
Blackouts
On this tab, you can view and edit monitor blackouts. Blackouts are time periods when the monitor either does not run or does not send alerts on errors. To learn how to create blackouts, see Scheduling Monitor Blackouts.
Existing blackouts are displayed in a table with the following columns:
| Column | Description |
|---|---|
|
Status |
The blackout status: Scheduled or Past. The column is shown if the Hide Past Blackouts check box is cleared. |
|
Schedule |
The blackout date and time. |
|
Type |
What is disabled during the blackout – the Monitor itself, or just Alerts from this monitor. |
|
Note |
Optional blackout notes. For one-time blackouts only. |
|
Created By |
The user who created this blackout. For one-time blackouts only. |
Click the image to enlarge it.
To filter out the blackouts, click the Filter by dropdown and select how to filter the blackouts:
-
By scheduling frequency: recurring or one-time blackouts.
-
By the blackout type: monitor or alert.
To remove expired blackouts from the blackouts table, select the Hide Past Blackouts check box.
Alerts
You can configure availability and performance alerts for the monitor. To receive alerts, you need to have alert recipients configured. By default, the monitor sends alerts to all configured recipients, but you can target alerts to specific recipients by selecting recipient groups for this monitor.
Recipient Groups (or Notifier Groups in AlertSite)
Select the recipient groups that will receive alerts from this monitor. The recipient groups must have been previously created in Alerts > Alert Recipients (or Notifiers > Notifier Groups in AlertSite 1.0).
 |
If the monitor is not assigned to any recipient group, it sends alerts to all the recipients configured in your AlertSite account. |
| Note: | Adding a monitor to the recipient group overrides any step-level associations for that recipient group. So if you want to add individual steps to a group, remove the monitor from that group first. |
Availability Alerts (or Notify on Error? in AlertSite 1.0)
Select this check box to send alerts when the monitor detects errors like HTTP errors, timeouts, or incorrect website content. The monitor status turns red in these cases.
Alert Notes
Monitor-specific notes that can be included in email and JSON alerts (availability alerts only), up to 1000 characters long. To add these notes to alerts, you need to configure alert templates to include the $ALERT_NOTE variable. For details, see Adding Monitor-Specific Notes to Alerts.
Performance Alerts
Enable performance alerts if you wish to be notified when the monitor response time exceeds the specified value. See Performance Alerts for a description of available settings and to learn how to set up these alerts.
Notes:
-
In AlertSite 1.0, click the Performance Alerts button in the top left corner of the monitor configuration screen to view or change the performance alert settings.
-
For multi-step monitors, the response time thresholds should include the total response time for all test steps.
Manage API project (AlertSite 1.0 only)
The Manage API Project button in the top right displays additional options to manage the SoapUI project associated with this API endpoint monitor.
Download Project
Click this button to download the SoapUI project that AlertSite generated for this monitor. You can run this project locally in SoapUI or ReadyAPI.
Convert to SoapUI
This button will permanently convert your API endpoint monitor to a SoapUI monitor. You will be able to edit the associated SoapUI project to add more test steps, assertions, data sources and other SoapUI features.
The conversion is one-way. SoapUI monitors cannot be converted back to API endpoint monitors.
For more information, see Converting API Endpoint Monitors to SoapUI.
See Also
API Endpoint Monitors
Creating an API Endpoint Monitor
Converting API Endpoint Monitors to SoapUI