API Monitoring Tutorial

AlertSite UXM’s API monitors run API tests created with Ready! API or SoapUI to check your API availability, correctness and response time from multiple locations around the globe. You can monitor both SOAP and REST APIs.

This tutorial explains how to create an API test, configure content assertions for API results, and upload the test to AlertSite UXM for monitoring. We will use the Country web service as an example:

It is a SOAP web service, but the procedure for REST web services is similar.

 

We will use Ready! API to create and configure the API test project. You can download a trial version of Ready! API here.

Note: If you already know how to create Ready! API test cases with assertions, or if you have an existing API test to use, skip to step 4.

In This Tutorial

Before You Begin

To create tests for a SOAP API, you need a WSDL file. The WSDL file describes API operations, parameters, the returned data structure, and other information about the API.

You can usually access the WSDL file by appending ?WSDL at the end of the web service URL. For example, if the web service URL is:

then the WSDL file is here:

1. Create a Project in Ready! API

Let’s start by creating a project in Ready! API:

  1. Select File > New SOAP Project from the main menu.
  2. Enter the Project Name, for example, CountryAPI.
  3. In the Initial WSDL text box, enter: http://www.webservicex.net/country.asmx?WSDL

    Creating a new SOAP project in Ready! API

  4. Click OK.

Your project should look like the following image. You can see that the API has two interfaces for different SOAP versions – countrySoap for SOAP 1.1 and countrySoap12 for SOAP 1.2.

API project

2. Create a Test Suite With a Test Case

Now we need to create a test case that would run API operations and verify their result.

Let’s create a test case for the GetCountryByCountryCode operation. This operation converts a two-letter country code to the country name (for example, FR to France).

To create a test case:

  1. In the project tree, right-click countrySoap12 and select Generate TestSuite.
  2. Select Create new empty requests.
  3. Under Operations, click Unselect all, then select GetCountryByCountryCode.

    Generating a test suite

  4. Click OK.
  5. You will see a message asking you to enter a name for the test suite. We will use the default name, so just click OK.

Now we have a test case with one step that calls the GetCountryByCountryCode operation.

A test suite with one test case

Many API operations have parameters. Be sure to specify the parameter values in the corresponding test steps. If parameter values are missing, the API may return errors.

In our example, the GetCountryByCountryCode operation has one parameter – a two-letter country code. Let’s use FR as this parameter’s value:

  1. Double-click the GetCountryByCountryCode test step. This opens the request editor.
  2. In the CountryCode text box, enter FR.

    Request parameter.

3. Create an Assertion

API tests should include assertions to check that the API works correctly and returns the correct results. Without assertions, the test checks only the API availability, but not the returned data.

Let’s verify that the GetCountryByCountryCode operation returns the correct results. In our example, it should convert FR to France. We already specified FR as the input parameter, so now let’s create the assertion:

  1. Click Run Request in the request editor to run the request. You will see the response in the right-side panel.
  2. In the response, right-click GetCountryByCountryCodeResult (the innermost item) and select Add Assertion > for Content.

    Adding a content assertion

  3. In the dialog that appears, review the Expected Result – it should contain France.

    Specifying expected value for content assertion

  4. Click Save.

You should see the green circle on the Assertions tab at the bottom of the request editor. This means the assertion has been successfully validated.

Valid assertion

4. Upload Project to AlertSite UXM

Now that you have a working Ready! API test, you can upload it to AlertSite for monitoring.

You can do this:

a. Uploading From AlertSite UXM

First, export your Ready! API project to a ZIP file:

  1. In Ready! API, select Project > Export from the main menu.

  2. Specify the ZIP file to create.

Then, in AlertSite UXM:

  1. On the Dashboard, click the big +, then + New Monitor.
  2. Select API and click Upload and Monitor.

    Upload a SoapUI project

  3. Select your AlertSite plan, and click Continue.
  4. Browse for your zipped API project, and click Submit File.
  5. Select your test case, and click Next.

    Select Test Case

  6. Enter the monitor name and how often it should run, and click Create.

    Configure API Monitor

  7. On the screen that follows, click Test on Demand. This will run the test from a remote location to ensure the monitor can work from arbitrary locations.

    Test on Demand

  8. If the test fails, review the errors and fix your Ready! API test appropriately, then export and upload the project again.

Congratulations! You have just created your first API monitor. It will start collecting data shortly, and you can see the results on the AlertSite dashboards.

API monitoring results in AlertSite

b. Uploading From Ready! API (Using AlertSite Connector Plugin)

Ready! API v. 1.3 and later include the AlertSite Connector plugin. With this plugin, you can create API monitors in AlertSite directly from Ready! API:

  1. In Ready! API, switch to SoapUI NG.
  2. Click Monitor APIs on the toolbar. This will open the AlertSite Connector:

    AlertSite Connector plug-in in Ready! API

  3. Enter your AlertSite email and password, and click Connect.

    Connect to AlertSite using an existing account

You will see the Connected to AlertSite message on successful login.

Now you can create an API monitor from your test:

  1. Click Add Monitors in the top left.

    Add Monitors

  2. In the dialog that appears, configure your monitor:

You will see the API Status page with your monitor added. The monitor will start running shortly, and you will see its status.

API Status

If you need to change the monitor settings (run interval, monitoring locations and others), use the Click here link to open AlertSite, and proceed from there. For details, see Editing a Monitor.

Useful Configuration Options

You may want to change the monitor settings in AlertSite to best fit your API monitoring needs:

For a complete list of settings, see SoapUI API Monitor Settings.

View SoapUI Logs

AlertSite stores SoapUI test logs to help troubleshoot API test failures. The logs contain full HTTP request and response data, assertion results, and any errors that occurred.

A SoapUI log is attached to email alerts if email recipients have the Attach server response to e-mail alerts option selected. You can also review the logs in AlertSite if the monitor has Capture Level enabled.

To view SoapUI logs in AlertSite, go to Monitors > Runs and select your monitor. Expand a failed run, then click Detail Report.

Opening the Detail Report

In the report that opens, click the camera icon.

Detail Report

The next screen lets you access SoapUI logs. View Step Log opens the log of just that step, and View Run Log opens the log of the whole run, including all step logs.

View SoapUI logs

Below is an example of a step log. You can see that the test failed, because the API response did not contain the expected value.

SoapUI log containing the request, response and assertion results

What’s Next

Learn About Creating API Tests

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