Using JavaScript to Validate HTTP Response Codes in API Responses

In addition to using JavaScript to validate HTTP headers received by your API Science monitors, JavaScript can be applied for fine-grained validation of the HTTP Status Code for each API response.

The status code normally associated with a successful response is 200 (“OK”). However, all 2xx status codes indicate that from the server’s point of view a valid request was received, it was processed, and an appropriate response was delivered to the client. The 2xx status codes that are greater than 200 provide additional information about the processing performed by the targeted server, or by a proxy server along the Internet path between the client and the target server.

The Internet is a complex system. Request and response traffic can be routed in many different ways, across multiple chains of proxy servers that relay the information packages. Another complication is caching, wherein data is stored in temporary locations along the path between a client and server. Caching is done to reduce the overall traffic level, thereby increasing the speed individual clients experience. Routing and caching are just two of the factors that can cause widely variable response times when the same request is repeatedly sent from the same client to the same server (as in one of your API Science  monitors). For example:

response_time_variationThe 2xx HTTP status codes report information about what happened at the server and what happened as the response package traversed the path between the endpoint server and the requesting client.

This three-digit code can be used by your monitor to let you make decisions about when your product will consider the API up, and when it will consider the API down. If the status code indicates that, while the request was successfully processed, the response body will not include information your product depends on, then there’s no need to even attempt to process the body: from your product’s point of view, the API is down.

Here’s a brief review of what the 2xx HTTP status codes mean (in addition to “Success”):

  • 200 OK: no additional information is provided
  • 201 Created: a new data item was created on the server
  • 202 Accepted: the server has received the request, but hasn’t finished processing it
  • 203 Non-Authorative Information: a proxy server sent the response based on a response from the endpoint server, but the response isn’t identical to the response the proxy received
  • 204 No Content: the server processed the request and returned no content
  • 205 Reset Content: like 204, but the requester should reset its data view
  • 206 Partial Content: the content is a subset of the entire data set because the request asked for this
  • 207 Multi-Status: the response body is an XML document containing additional status information
  • 208 Already Reported: a follow-on related to 207
  • 226 IM Used: the response is a representation of one or more instance manipulations (IMs) applied to the current instance

If the response from this API is critical for your product, clearly status codes 200 and 201 are perfect, but status code 202 makes the API down. The remaining status codes are more complex: depending on the software that creates your product, API responses with some of these status codes may represent responses that can be processed.

Assume we’d like to have the API check fail if the HTTP status code is any value other than 200 or 201. Here’s how we implement that using API Science’s JavaScript validation. Edit the monitor, click “Show settings” and select “JavaScript” in the “Validations” pull-down menu:

xkcd_javascript_entry

In the text box, enter:

var statusCode = context.response.meta.statusCode;

assert( statusCode == 200 || statusCode == 201, 
        "Expected a 200 or 201 response");

Then, at the bottom of the page, click the “Save Monitor” button.

We’ve now created a JavaScript validation that will say the API check failed if the response HTTP status code is anything other than 200 or 201.

–Kevin Farnham

One thought on “Using JavaScript to Validate HTTP Response Codes in API Responses

Comments are closed.