Using Regular Expressions and JavaScript to Validate API Responses

Regular expressions (RegEx) are “a sequence of characters that define a search pattern, mainly for use in pattern matching with strings, or string matching.” Amazingly, the RegEx concept was invented back in the 1950s, by U.S. mathematician Stephen Cole Kleene, who was a student of Alan Turing, among others.

In his book Mastering Regular Expressions, Jeffrey E. F. Friedl writes:

Regular expressions are the key to powerful, flexible, and efficient text processing. Regular expressions themselves, with a general pattern notation almost like a mini programming language, allow you to describe and parse text. With additional support provided by the tool being used, regular expressions can add, remove, isolate, and generally fold, spindle, and mutilate all kinds of text and data.

Consider a response body from an API that your product depends on. Your product sent a request to the API, and a response was returned. But does that response contain the information that your product needs in order for your product to appear “up” to your customers?

API Science’s JavaScript validation capability provides you with the opportunity to apply regular expressions to analyze the content of an API’s response body, even down to the level of the text that’s in a particular JSON field. In this post, I demonstrate this capability.

My XKCD API monitor queries the XKCD API. A successful response has a body that looks something like this:

{
  "month": "2",
  "num": 1481,
  "link": "",
  "year": "2015",
  "news": "",
  "safe_title": "API",
  "transcript": "((This is a faux-screenshot of a technical document))\n[[A figure sits at a computer upon a desk, apparently engrossed in the document which we now see before us.]]\nTITLE: API GUIDE\nRequest URL Format: domain\nuser\nitem\nServer will return an XML document which contains the requested data and documentation describing how the data is organized spatially.\nAPI KEYS: To obtain API access, contact the x.509-authenticated server and request an ECDH-RSA TLS key...\n\nCaption: If you do things right, it can take people a while to realize that your \"API documentation\" is just instructions for how to look at your website.\n\n{{Title text: ACCESS LIMITS: Clients may maintain connections to the server for no more than 86,400 seconds per day. If you need additional time, you may contact IERS to file a request for up to one additional second.}}",
  "alt": "ACCESS LIMITS: Clients may maintain connections to the server for no more than 86,400 seconds per day. If you need additional time, you may contact IERS to file a request for up to one additional second.",
  "img": "http://imgs.xkcd.com/comics/api.png",
  "title": "API",
  "day": "2"
}

This is a JSON response body. The API Science JavaScript validation capability enables you to inspect JSON responses on a field-by-field basis.

Let’s say the information that’s critical for you product is located in the transcript field in the JSON body: if the word “faux” isn’t in the body, then the API is down as far as your product is concerned, because your product integrates what follows that text into the result you present to your customers.

How can you verify that the XKCD API is “up” for your product using your API Science monitor? It’s easier than you might think, using JavaScript and regular expressions…

Edit your monitor, and click “Show Settings”. In the “Validations” pull-down menu, select “JavaScript”:

xkcd_javascript_entryEnter the following into the text window:


var body = JSON.parse(context.response.body);

assert( body.transcript.search(/faux.*/i) > -1, 
              "transcript field does not contain 'faux'");

The regular expression is the text contained within the parentheses following search. What does this RegEx mean?

The /faux.*/ means the text should be searched for the text “faux”; if that’s not found, the search fails. The “.” means that “faux” must be followed by at least one character (i.e., the “faux” that was found cannot be at the end of the string). The “*” means that any number of characters can be in the string after “faux” (these characters would likely be the ones your product depends on). The “i” after the last slash means that the string should be analyzed in a case-insensitive manner (which might or might not be fitting for your particular application).

Save the updated monitor. Now, if a response is ever received where the JSON body’s transcript field doesn’t contain the word “faux” followed by other characters, your API Science monitor will declare the XKCD API “down” — and it will be time for your team and/or software to take appropriate action on your customers’ behalf!

–Kevin Farnham