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:
- Setting the HTTP method, URL, request headers and request body for each request.
- Adding authentication (Basic/NTLM/Digest/OAuth) or including client certificates to gain access to protected APIs.
- 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 API monitor
To add a multi-step API monitor:
- Select from the Monitors menu.
- Select Multi-step API from the Type list.
- Give your monitor a Name.
- 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.
The Request tab contains all of the data needed to perform the actual HTTP request in the step. At a minimum:
- Choose the appropriate HTTP method (either GET, POST, PUT, PATCH or DELETE. If you need a different method, contact us).
- 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.
- Optionally fill in a short description for this step. This description will appear in the monitor check results.
When specifying a POST, PUT, PATCH 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.
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:
- Click on the button to add a request header key and value.
- Fill in Content-Type as the header key.
- The appropriate header value depends on the data you’re sending. The most common content types are
application/jsonfor JSON data,
text/xmlfor XML data, and
application/x-www-form-urlencodedfor webform data.
Similarly, if your API requires you to include authentication, include a header
Authorization along with the appropriate data in the Value field.
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.
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).
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.
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:
More examples of Variables: How to define and use variables.
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.