Contents ▼

Basic HTTP Steps

Each ordinary step in your monitor makes a single HTTP request. You specify the method, URL, and headers to be sent. If it's a method that supports a body (like a POST or PUT) you can supply a body too.

You can think of each HTTP step rather like a visual representation of a curl command.

Most basic monitors in Speedway will have one or more HTTP steps, which Speedway executes sequentially with each monitor cycle.

Method

Many APIs, especially RESTful APIs, have different behavior depending on which HTTP Method you call them with. While GET is the most common, and hence the default, you have a variety of methods to choose from for each step.

URL

You didn't make it this far without knowing what a URL is! For now, let's just say each step in your monitor needs to specify what URL it is going to hit. Because some monitors might hit a variety of different domains back-to-back (like an OAuth flow for example), the full URL is required for each step.

Request Body

Certain HTTP methods, like POST or PUT, commonly include a request body. This can have any Content-Type you want, and will typically include some content, but sometimes an empty body is acceptable. For other HTTP methods like GET, Speedway does not prompt you for a request body.

You can edit text-based request bodies (JSON, XML, plain text, etc) in Speedway. Binary or unusually large bodies can be loaded via your browser's file manager.

You might also notice an option called Interpolate variables in request body. This deals with the treatment of variables and expressions that might occur in your request body. If checked, strings like ${variable} and ${expression()} occurring in the body will be substituted with their respective values, or an empty string if undefined. If unchecked, such strings will be sent literally and not interpolated.

Custom Headers

Speedway sends some default HTTP headers with each request, but you can also add your own custom headers. This is often necessary if your API requires certain authentication/authorization schemes, among other things.

To add a custom header to a step, select Add custom header under the Add… menu.

HTTP headers are simple name value pairs. If yours are dynamic (in other words, they might be different each time your monitor runs), you can use variables and expressions in either field.

Basic Authentication

While it's become a little less common in recent years, many APIs still accept HTTP Basic Authentication as a way to pass username and password to identify the caller. The username and password might be an actual username and password, or they might be some kind of API key.

To configure HTTP Basic Authentication for a step, select Add basic authentication under the Add… menu. Enter a username and password, either of which may be literal strings or be comprised of variables and expressions.

Validators

You can add special Validators on an HTTP step which will examine the response that comes back from the API. All types of validators are under the Add… menu.

If any validator on any step fails, the entire monitor cycle is deemed a failure, and Speedway will immediately send out notifications if this monitor was previously passing.

Content Validators

This type of validator can quickly check whether the response body includes (or does not include) a certain string.

Response Time Validators

These validators can ensure a request is made and the response fully received within a certain amount of time. This is good for critical API operations that simply must complete quickly.

Response Size Validators

Use these to quickly validate that the response body is within a certain size range. This is often a good way to check for the presence of errors or unreasonably large API responses.

JavaScript Validators

These are the most powerful kind of validator in Speedway! A JavaScript validator lets you specify a custom JavaScript function called validate() that Speedway feeds the response to, after executing an HTTP step.

You can put whatever validation logic you want in the function, and return true or false.

If the validator function returns a true value, then validation is deemed to have passed. If it returns false (or a falsy value such as null or 0) then it is treated as a failure.

The JavaScript flavor and runtime environment is described in more detail in Advanced Code Blocks.

Capturers

You can also add Capturers that examine the response coming back from your API. Capturers can be found under the Add… menu on any HTTP step.

Capturers can examine a response and extract an actual value, which Speedway then stores in a variable for use by a subsequent step.

A few real world examples of when you might use capturers for API monitoring include:

  • A monitor is hitting a login endpoint, and needs to extract the dynamic api_key that the API returns after successful login, for later use in the same monitor sequence.
  • You hit an API endpoint to create an invoice, and need to reuse the dynamically created invoice_id later so you can apply a credit.
  • You hit a list endpoint and obtain a list of vehicles, and need to grab the first vehicle_vin_number to hit a detail endpoint.

In short, capturers are one of the most powerful constructs in Speedway's approach to monitoring. They set it apart from many of the simple uptime monitoring tools.

Text Capturers

Simple text capturers can extract a string of text from a response header or the response body, using the “sandwich” method of a literal left and right bound. For example, in the string “you have 18 new messages”, you could capture the number of new messages using a left bound of “you have " and a right bound of " new messages”.

Regex Capturers

A regex, or regular expression, is a more sophisticated way to parse strings. We won't include a full regex primer here, but if you're a developer and haven't done much with them yet, it's worth knowing! Like simple text capturers, regex capturers can extract values from a response header or the response body, but they also support capturing groups to reorder or restructure the value. For example, we could parse the email address "Andy Hawkes" <andy@speedway.app> with a Regular Expression of ^"(.*?)" <(\S+)>$ and an Output Expression of $2: $1, in which case the extracted value would be stripped of formatting and reordered to `andy@speedway.app: Andy Hawkes`.

JavaScript Capturers

Most powerful of all, these capturers let you write your own JavaScript function to extract whatever you want from the response. The function can even do advanced JSON or XML parsing, looping, conditionals, pattern matching… pretty much anything you can think of that is possible in a highly capable scripting language like JavaScript.

Your capturer function should be called capture and return the value that you want to store in the variable for later use.

The JavaScript flavor and runtime environment is described in more detail in Advanced Code Blocks.