User-defined functions in Multi-Step API Monitoring

When it comes to monitoring your API, you need a tool that has the flexibility to handle the complexities of a modern website or app. Uptrends’ Multi-step API Monitoring gives you the power to interact with API endpoints, evaluate the results, reuse response data, create automatic variables, track custom metrics, and now transform response data with user-defined functions.

First things first: Multi-step API

Before we dive into user-defined functions, we should go over the basics of Multi-step API monitors.

Why use Multi-step API Monitoring

If your business publishes an API (application program interface) or your business relies on one, you need to verify that it works properly around the clock. You can set up monitors to confirm that the server responds, but that doesn’t prove the API works. Multi-step API allows you to make complete API transactions through multiple API calls and even multiple APIs.

• Define your API requests:
  You have full control of your requests from the HTTP method, headers, body, and your authentication credentials and certificates.
• Analyze the response: You have the control to make assertions on the response, such as response time, status code, response body values, cookies, and content length. Use variables to pull values from the response for use later in other API calls.
  
• Set up predefined or automatic variables: Predefined or automatic variables give you the ability to define variables during the set up that you later assign values to when the checkpoint starts the test. For example, you may want to store credentials in a predefined variable for reuse on multiple requests, or you may want to capture a date/time stamp for use as a unique user id when testing account creation.
• Track custom metrics: Custom metrics is a bonus. If your API returns numeric data that you would like to track and chart, custom metrics lets you track and even issue alerts on them. For example, if your API returns the number of active orders in the queue, you may want to get alerts when the number reaches certain thresholds.
  

Now Multi-Step API Monitoring supports user-defined functions

Sometimes when grabbing content from the response for use in a later request, the data isn’t in the right format. For example, the API responds with either a one or zero (Boolean), but for the next request, you need to pass either the character string “true” or “false,” user-defined functions let you make the switch.

Mapping values

Mapping is a simple “I want to take this value and replace it with this other value.” Our example above is a simple mapping example. Let’s take a look at how you would set up this function in your API steps.

Set up your function

1. Click +Add function
2. Select Mapping
3. Name your function
4. Enter your mapping values. In this case, we want to map “0” to “false” and “1” to “true”.
5. Click Add mapping to map “1” to “true”.

Once entered, you’re done. Your function is now ready for use in your steps. Let’s take a look at how to use the function in your responses.

Using your mapping function

Using the function requires that you first extract the response value to a variable. Learn more about defining and using variables in your API monitoring.

After you’ve extracted your value to a variable, you can apply the mapping function. The first line in the figure below extracts the value from the JSON response and stores the value in a variable named is_active_boolean. Once stored in a variable, you’re ready to map the value using your function.

1. Click Add variable.
2. Select Execute function in the first box.
3. Set the Function expression (second box)
   1. Enter the function name in the from box (the second box) followed by an open and closed parenthesis. For example, boolean_to_text().
   2. Place double curly braces around the entire expression. For example, {{boolean_to_text()}}.
   3. Place the variable name that holds the original value within the parenthesis with curly braces around the variable name {{boolean_to_text({{is_active_boolean}})}}.
4. Enter a variable name to receive the mapped value. In this case, the value is either “true” or “false”.

Now you can reference the new variable in future calls to send the text value rather than the Boolean result.

User-defined functions using regular expressions

The process of using regular expressions works the same way as mapping functions. Use regular expressions (also called RegExp) to extract values from text strings previously stored in a variable. Use regular expressions to perform complex pattern matches that parse the value from a string of characters. Learn more about regular expressions.

Conclusion

With user-defined functions, we continue to expand the API monitoring possibilities available to you. User-defined functions are also available in your webhook integration setups.

We have more detailed set up instructions for you in our Knowledge Base. If you need help setting up your user-defined functions, our Support team is here for you. Just open a support ticket, and our heroes will help you along.