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!

Multi-step API monitoring is a new feature which is currently in beta. We're working towards a public release, but you can already try it today! Please contact Support to request early access. We'll enable Multi-step API monitoring in your account so you can get started right away.

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:

  • Setting the HTTP method, URL, request headers and request body for each request.
  • Defining assertions (checks) for each response, to verify the HTTP status code, content checks (based on plain text, JSON content or XML content), request duration and more.
  • Extracting content from the response body, response headers, cookies and storing them in variables. Those variables can be used in later steps to build new URLs, request headers, etc.

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 HTTP monitor

To add a multi-step HTTP monitor:

  1. Select + Add Monitor from the Monitors menu.
  2. Select Multi-step HTTP from the Type list.
    If you don't see this option, your account is not part of the beta program yet. 
  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 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.

Configuring a 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

Request in Multi-step API Monitoring

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, or DELETE. 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 or PUT 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. 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.

Response

Variables in Multi-step API Monitoring

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.

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.