Last modified on August 9, 2018

An API endpoint monitor sends one or more HTTP requests to an API and checks the response time, status and response contents. For each step (request), you can define assertions to verify the response data. You can also define variables to extract data from responses and use it in subsequent requests.

API monitors can also be created from OpenAPI (Swagger) definitions or by uploading a ReadyAPI or SoapUI project.

Create a monitor

Start on the AlertSite UXM Dashboard, hover over + Add New, then select Monitor from the dropdown. Select API on the left, then click Single API Endpoint Monitor.

Creating an API endpoint monitor in AlertSite

Click the image to enlarge it.

Configure HTTP request (URL, headers, body)

On the next screen, you can configure the request – specify the URL (including http:// or https://), request method (GET, POST or other), headers and body. The body is used only for POST, PUT, and PATCH requests.

Alternatively, you can click Swagger and import an OpenAPI (Swagger) definition that describes your API endpoints and parameters.

Configuring an API request in AlertSite

Click the image to enlarge it.

If you are sending a request body, such as JSON or XML, select the appropriate content type from the list. To use a different content type, select Custom and add the corresponding Content-Type header manually.

Notes:

  • Query string parameters should have unique names. Multiple parameters with the same name (such as ?tag=cats&tag=dog) are not supported.

  • When sending a body, make sure the body syntax is correct. AlertSite’s request editor validates the JSON syntax. If you are posting XML, use www.xmlvalidation.com to check your XML syntax.

Authentication

Basic authentication

API endpoint monitors support Basic authentication. It is a widely used method for simple username/password authentication and involves sending the encoded credentials in the Authorization header in requests.

To authenticate the request, switch to the Authentication tab and enter the username and password.

Username and password for Basic authentication

Click the image to enlarge it.

With some servers, you may also need to select the Authenticate pre-emptively check box to authenticate successfully. This will send the Authorization header in the initial request, instead of expecting a 401 response before retrying the request with the credentials.

You can authenticate API requests in other ways as long as this involves passing some static values in the request URL, headers or body (that is, no additional API calls or things like real-time timestamps). Refer to the API documentation to learn what kind of authentication the API uses. Below are some examples.

API Keys

API keys are usually sent as a query parameter:

https://api.example.com/users?api_key=abcde12345

or as a header, such as:

X-API-Key: abcde12345

API endpoint monitors support both ways.

SSL Certificate

AlertSite supports client-side certificates for API endpoint monitors. After you create the monitor, you can upload the certificate to AlertSite and assign it to the monitor. For details, see Using SSL Certificates and Java Keystores.

Query parameters

If the target URL uses query parameters, such as http://api.example.com/photos?tag=cats&size=large, you can append them directly to the URL, or specify them in the Parameters table. The request URL and the Parameters table are synchronized and automatically updated as you change either of them.

The parameter editor is handy if some parameter values contain reserved characters such as % ! & or others – you can enter the values as they are, and AlertSite will automatically encode these values in the request URL.

Click to add a new parameter, or to delete a specific parameter.

Query parameter editor

Click the image to enlarge it.

Note: Query parameters must have unique names. AlertSite API monitors do not support multiple query parameters with the same name.

Validate request

After you have entered the request data, click Validate Step to send a sample request and see the response. If there is an error, double-check the request configuration (URL, headers and body).

After validating the request, you will be able to add assertions.

Assertions

Assertions are used to verify the data returned in the response body. For example, you can check the value of a specific JSON field, or search for a specific word in the response text. When a monitor runs the test, it is considered successful only if all of the assertions pass.

To add an assertion, click a line in JSON or select text in a text response, and click Add Assertion. You can also add assertions manually to the table. To learn more, see API Assertions.

API assertions

Click the image to enlarge it.

Add more steps

Click Add Step to add another request at the end of the test. This way you can create a sequence of chained API calls that use variables to pass data between the steps. AlertSite will run the steps in sequence, and the test will be considered successful only if all steps are successful. If a specific step fails, the rest of the steps will run.

Here is an example of a 3-step monitor:

API test steps

Click the image to enlarge it.

Note: The maximum number of steps a monitor can have depends on your AlertSite plan. On most Usage-Based Monitoring plans, it is 50.

After you have configured the steps, click Validate Monitor to test the requests. This runs a basic test with variable substitutions and checks for response status 2xx or 3xx. The Step Summary will indicate the step status:

 – OK (the request is successful, all assertions passed).

 – one or more assertions failed, or there is a problem with variable extraction.

 – a response status other than 2xx or 3xx.

Variables

In multi-step monitors, you can use variables to extract data from JSON and XML responses and insert it into subsequent requests. See Variables for details.

Other monitoring settings

After you have configured all the steps, requests, and assertions, click Next to proceed.

On the next screen, you can give your monitor a name, select the run interval, and the locations where the monitor will run. More settings are displayed if you click Edit Configurations in the top right corner.

Some useful settings are:

  • Step timeout – maximum acceptable response time for each step.

  • Capture level (accessible via Edit Configurations) – lets you store the request and response contents from the test runs.

For a description of all the settings, see API Endpoint Monitor Settings. You will be able to change all the settings later, if needed.

Selecting locations for an API endpoint monitor

Click the image to enlarge it.

Once done, click Start Monitoring Now in the top right corner to create the monitor.

AlertSite will now monitor your API endpoint and alert you on errors. The first results will appear on the AlertSite Dashboard in a few minutes.

What’s next

FAQ

Which HTTP status codes are considered successful?

The following HTTP status codes are considered successful:

  • 100, 200, 201, 202, 203, 204, 205, 206

  • 301, 302, 303, 306 (to make them errors, select the Report redirects as errors monitor option)

  • 401, 403 (to make them errors, select the Report authentication challenges as errors monitor option)

Any other codes are considered errors.

Is there a timeout for HTTP requests?

The request timeout is 1 minute (60 seconds) and is not configurable. However, the Step timeout lets you set the acceptable response time for requests. Steps with a longer response time will have error status 6570 in the monitor run results.

To use custom request timeouts, you will need to convert your API monitor to SoapUI and adjust the timeouts in the SoapUI project.

Is there a timeout for the entire test?

The time limit for the entire test is 10 minutes on AlertSite global monitoring locations and 20 minutes on private nodes. Tests that exceed the limit will trigger error 81 - “Maximum transaction time was exceeded”.

See Also

API Endpoint Monitor Settings
Converting API Endpoint Monitors to SoapUI
Creating API Monitors From OpenAPI (Swagger) Definitions

Highlight search results