1. Support
  2. Knowledge base
  3. API Monitoring
  4. Setting up Multi-step API Monitoring

Setting up Multi-step API Monitoring

We’re changing our user interface. Some info may not yet be up to date. Please check From classic to new UI.

To monitor your API properly, you often need to use multiple HTTP requests. Usually, you’ll want to set up a sequence of requests, where each new request uses one or more pieces of data retrieved from a previous request to perform its task.

Possible reasons for wanting to run a sequence of HTTP requests are:

  • Your API requires authenticated access. In order to call a method in the actual API, an API client must first authenticate (e.g. using OAuth authentication).
  • You want to test a functional scenario in your API consisting of multiple steps that are typically executed in a particular sequence by your end users.
  • One of your HTTP requests returns a redirect to a different URL, but you want to inspect that response before following the redirect.

For any of these scenarios, Multi-step API Monitoring is a great fit!

An API scenario can start out as just a single step, but you can add more steps yourself and even expand your scenarios later on. You have full control over the complete HTTP request content. Features include:

These features help you to ensure that your API is behaving correctly and performs within the limits you specify. The step-by-step approach allows you to start setting up very powerful scenarios without adding complexity. As long as you know how your API should behave, you don’t need to have any programming skills to get started with API monitoring.

Creating a multi-step API monitor

To add a multi-step API monitor:

  1. Select + Add Monitor from the Monitors menu.
  2. Select Multi-step API from the Type list.
  3. Give your monitor a Name.
  4. Switch to the Steps tab to input the details for each step.

Your new monitor starts out with one (empty) step. Go ahead and click the + Add request step button to add additional steps. You’ll see that the list of steps grows. Click on a step to edit its details. To remove a step, click on the Delete step button that appears when you move your mouse pointer over the step list.
Similarly, click on the Duplicate step button to create a copy of an existing step. You can also change the order of the steps using the Move step up and Move step down buttons.

Configuring a Request step

Looking at the first step of our monitor, you will notice two tabs on the right side of the screen: Request and Response. Let’s review them.

Request

The Request tab contains all of the data needed to perform the actual HTTP request in the step. At a minimum:

  1. Choose the appropriate HTTP method, either GET, POST, PUT, PATCH, DELETE, HEAD or OPTIONS. If you need a different method, contact us.
  2. Fill in the URL for the request. Use a fully qualified URL, including the schema (“https://” or “http://"), the domain name and path for your API, and any query string parameters you want to include.
  3. Optionally fill in a short description for this step. This description will appear in the monitor check results.

Request body

When specifying a POST, PUT, PATCH, HEAD, OPTIONS or DELETE request, the Request body field appears. Specify the data you want to send as part of the request (most likely JSON data, XML data, or encoded form data). In most cases, your server will expect you to specify the format of the data you’re sending so it knows how to read and deconstruct that data. To do this, you’ll need to add a Content-Type request header as described in the next paragraph.

Request headers

An HTTP request usually contains some request headers to specify the format of the data that’s being sent, or to further describe what kind of response is expected. When setting up a request step, you’ll notice that certain headers are added automatically. These headers consist of a default set, depending on the type of request you’re making (GET requests will have a different set of headers than POST requests, for example). A default header may be overridden (with the exception of the Content-Length header), simply by adding a new header with exactly the same name as the existing one, but with a different value.

New headers may also be added. For example, to add the Content-Type header mentioned earlier, follow these steps:

  1. Click on the Add request header button to add a request header key and value.
  2. Fill in Content-Type as the header key.
  3. The appropriate header value depends on the data you’re sending. The most common content types are application/json for JSON data, text/xml for XML data, and application/x-www-form-urlencoded for webform data.

Similarly, if your API requires you to include authentication, include a header Authorization along with the appropriate data in the Value field.

Examples of request headers

The image above shows an example of a request step. Notice the following:

  • It is a POST request to https://www.galacticresorts.com/api/Reservation
  • The default headers set for this request are:
    • Host
    • Accept-Encoding
    • Connection
    • Content-Length
  • The values for the Host and Content-Length headers will be determined upon sending the request.
  • Manual headers Content-Type and Authorization have been added, to specify the data format and provide the necessary credentials, respectively.
  • Default header Connection has been overridden.
  • The request body contains some x-www-form-urlencoded content.

Authentication

A lot of APIs are protected and can only be accessed by supplying login credentials. If your API uses authentication on the HTTP protocol level, choose your type of authentication (Basic, NTLM or Digest) and fill in the corresponding username and password. Alternatively, you can set up OAuth based authentication using separate steps. More information on setting up built-in or custom authentication.

Using a credential set from the vault

It is possible to use vault credential set references at any point as part of the request body, request headers, or as the value for your username/password under Authentication. To refer to a vault item, use the following syntax: {{@VaultItem.<itemGuid>.Password}} or {{@VaultItem.<itemGuid>.Username}} depending on which value is required. To find the itemGuid, navigate to the vault item with the credential set, then copy the last part of the URL in the URL bar of your browser.

Examples of vault item references

Response

The response tab contains all options for performing checks on response data (using Assertions) and processing that data in preparation for the next step (using Variables).

Assertions

Defining your steps and feeding the correct data into those steps is the ground layer for a useful setup. However, it’s also important to look at the results of each step. Just calling a series of URLs is no good if they’re not returning the right results. Assertions help you with those health checks.

Assertions are checks you can execute to verify that the response in a particular step behaved as expected, for example, by checking its content or verifying that it was retrieved within a certain amount of time. Like with variables, you specify the source for the check, e.g., a JSON property from the JSON response body, an XPath query on the XML response body, or even just the status code of the response, its duration or content length.

More examples of Assertions: read our extensive guide for defining assertions.

Variables

When you’re setting up multi-step scenarios, it’s likely that at least one of those steps depends on some input retrieved during a previous step. By capturing that input, storing it temporarily and taking it across to the next steps, you’re creating a natural progression of connected steps, without the need to write any code.

Variables let you do exactly that! Each step can create new variables and has access to variables created by other steps, so you can re-use data that was captured previously in the scenario.

You can define where a variable should come from: probably a particular value from JSON or XML data, but capturing response headers or even data from a redirect is also possible. After a variable has defined, you can use it anywhere in your multi-step setup simply by referring to it by name: {{my-variable}}.

More examples of Variables: How to define and use variables.

Retry until successful

In some cases, it may be that your API needs some time to process an incoming request before it can respond indicating a success. For example, let’s say you upload a file to your API for processing. While it’s processing, the API responds to requests regarding the status with {"result":"processing"} in a JSON body. Once processing finishes, the API starts responding with {"result":"success"} instead. In such cases, you can configure the monitor to keep polling the API until it responds with a success by using the Retry until successful function.

This function will set the monitor to retry the step if one or more of the assertions in the step (such as Response body as JSON result Is equal to success for the example mentioned above) fails. You can set how many retries the monitor should attempt (up to a maximum of 50 retries). Each retry will be executed with a one second wait in between. Simply enable the option in the Response tab of a step and set the number of retries that should be attempted.

MSA step retry

The monitor will continue retrying the step until either the maximum number of retries is reached or every assertion passes. At that point, the monitor will proceed as normal, executing the rest of the steps in order. If the maximum number of retries is reached, and still at least one assertion fails, the monitor will report an error in the monitor log.

Note that the cost of the MSA monitor remains the same, regardless of the number of retries it uses.

Configuring file uploads

Multi-step API monitors allow you to upload files from your vault as part of one of your request steps. Any HTTP steps you configure in the Multi-step API monitor that contains a request body may be either a file upload or a regular plain text request. Files will be sent as multipart/form-data content. To set this up, follow these steps:

  1. Upload the file in question to your vault. The maximum file size is 2 MB.
  2. In the settings of your Multi-Step API monitor, add a request step or use an existing step to execute the file upload.
  3. In the Request tab of the step that should execute the file upload, set the request method to POST, PUT, or PATCH (depending on which you require) and fill in the request URL.
  4. Under Request body, select option Upload a file from the vault.
  5. Click the Add file from vault button that appears.
  6. Choose the appropriate file from the Vault file upload list, and click the Select button. File upload picker
  7. It is not necessary to add any specific request headers. We will automatically set a request header for Content-Length and set Content-Type: multipart/form-data with the correct boundary. Example headers for file upload

Configuring a Wait step

When you’ve added a sequence of Request steps to your monitor, each step will be executed as soon as the previous step finishes, without any delay. However, this immediate execution may be a bit too quick for some scenarios.

Consider an API method that acts as a request for a report file to be generated. The API kicks off a backend process that will generate the file, and instructs the caller to send a second request in order to download the new file. Generating that file may take a second or two, so the caller should wait for a few seconds before sending the second request. If the second request is sent too soon, it will fail since the generated file isn’t ready yet.

For this scenario, it’s important to wait before the second request is executed. To do this, you can insert a separate Wait step. This type of step allows you to specify the number of milliseconds to wait. For example, to wait 3 seconds, specify 3000 milliseconds as the wait time. This wait time will be included in the total time metric for this monitor.

To add a wait step, simply click on the + Add wait step button and specify the number of milliseconds you want to wait. If necessary, you can move the wait step to the right spot in your scenario using the Move step up/down buttons.

The wait time for a wait step is limited to 60 seconds: a wait step is not intended to monitor a long-running task that takes several minutes or hours. If the monitor exceeds the maximum total running time, the check will stop running and a failure will be reported.

Adding a wait step to your monitor doesn’t cost you anything. The cost of a Multi-step API monitor is only based on the number of Request steps.

Multi-step monitor results, errors and alerting

Multi-step API monitors behave in the same way as any other monitor. Each check appears in the monitor log, and displays extensive information for each individual step. For each step, this information consists of:

  • the total duration of the step (in milliseconds),
  • the URL that was executed during that step,
  • the HTTP status code that was returned,
  • the result for each assertion (pass or fail),
  • the request headers and content that we sent,
  • the response headers and content that we received.

If a problem occurs during one of the steps, or if one of the assertions you defined does not pass, the monitor will fail and report an error. As usual, these errors can generate alerts based on your alert definitions.

By using the Uptrends website, you consent to the use of cookies in accordance with our Cookie Policy.