Using JavaScript to Validate API Response Bodies

In prior posts, I’ve illustrated how API Science’s JavaScript validations capability can be used to validate API response timing versus data size, API HTTP response headers, and HTTP response status codes. What hasn’t yet been investigated is how you can use the API Science JavaScript validation facility to validate the API response body.

We’ll use my XKCD monitor to see how this can be done. This monitor queries the XKCD API using a simple GET request sent to this API endpoint:

http://xkcd.com/1481/info.0.json

When the API is up, it returns an API response body similar to 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: a list of keys, followed by a colon, followed by a value. In your API Science monitor, you can use JavaScript to validate any of these fields.

Let’s say your API at this moment relies on the response “day” value to be “2”. If the API isn’t returning this JSON value, then, from the point of view of your product, the API is down.

To configure this validation into your API Science monitor, edit the monitor, and click “Show Settings”. In the “Validations” pull-down menu, select “JavaScript”:

xkcd_javascript_entryEnter the following code into the text window:


var body = JSON.parse(context.response.body);
var day = "2";

assert.equal( body.day, 
              day, 
              "Wrong day");

This code inspects the API’s JSON response body’s “day” variable, and tests if its value is “2”. If the value is “2” then the API check validation passes. If the values isn’t “2” then the check fails.

What will you see in your API Science monitor if this type of validation fails? “2” is the expected response for my XDCK monitor. If I edit the second line of my JavaScript validation code to be:

var day = "3;

and I then run my monitor, I will see this in the result:

xkcd_wrong_dayThe API is down from your product’s point of view, because your product depends on the value of the “day” variable for this particular query to be “2”.

JavaScript is a vast programming language that supports highly-detailed investigation of content that is returned in API response bodies. API Science provides unlimited ability for you to analyze response bodies to determine if, from your product’s point of view, an API you depend on is up or down.