Help Index


Parameters

You can set any number of query string, POST, and PUT parameters using the Params input fields. Each time you add a new parameter a new pair of Key/Value input fields will display. You can also append parameters directly to the URL as ?param1=value1.

Headers

You can set any number of request headers using the Headers input fields. For example a key of "Content-Type" with value "application/json". Each time you add a new header a new pair of Key/Value input fields will display. As noted below, JavaScript variables assigned in a script can be used as header values using the syntax {{variable}} in the value field.

Validations

Validations allow you to perform tests against the results of each call. Four types of validations are available:
  • Return code: Validate against specific HTTP return codes such as 200, 201, 302, etc. If this code is not returned the validation will fail and this monitor will be considered to be in a "failed" state.
  • JSON: Validate that the body of the response is valid JSON.
  • Regex: Search the response body for a regular expression. This can be an ordinary string such as "Welcome", or a more complex regular expression such as "1.*9".
  • JavaScript: Execute your own custom JavaScript for advanced testing of call results. By default API Science embeds the Chai JavaScript library for running test assertions. Any assertion failure will flag this validation as failed and in turn will cause any user-defined alert rules to be triggered.
     

    The following examples demonstrate the range of validations you can perform:

    var body = JSON.parse(context.response.body);
    var cityName = "Armonk";
    
    assert.equal( body.location.city, 
                  cityName, 
                  "Expected " + cityName);
    
    var pragma = context.response.headers.Pragma;
    
    assert(pragma == 'no-cache', "Wrong pragma " + pragma);
    
    var contentType = context.response.headers['Content-Type'];
    
    assert( contentType.indexOf("application/json") >= 0, 
            "Not a JSON response");
    
    var timing = context.response.timing.total;
    var size = context.response.meta.downloadSize;
    
    // Fail if call took over 5 seconds but not over 10K payload
    if (timing > 5000) {
      assert(size > 10000, "Download size vs speed issue");
    }
    
    var statusCode = context.response.meta.statusCode;
    
    assert( statusCode == 200 || statusCode == 201, 
            "Expected a 200 or 201 response");
    
    var body = JSON.parse(context.response.body);
    
    assert.equal(body.user_id, 
                 199934, 
                 'user_id should be 199934');
    
    assert( body.subject.value.replace(/ /g,'').length > 12, 
            'subject length should > 12');
    
    var body = JSON.parse(context.response.body);
    
    assert( body.customers.length > 10, 
            'Should return at least 11 customers');
    

JavaScript Validation Reference

  • context.request.url: Url of request.
  • context.request.headers: An object of request headers.
  • context.request.params: An object of request parameters.
  • context.request.body: POST body (if HTTP method is POST).
  • context.response.headers: An object of response headers.
  • context.response.body: Response body.
  • context.response.timing.resolve: DNS resolve time in milliseconds.
  • context.response.timing.connect: Call connect time in milliseconds.
  • context.response.timing.transfer: Call transfer time in milliseconds.
  • context.response.timing.closing: Call closing time in milliseconds.
  • context.response.timing.total: Total call time in milliseconds.
  • context.response.meta.contentType: Content-Type of call response.
  • context.response.meta.downloadSize: Size of call response in bytes.
  • context.response.meta.statusCode: HTTP status code of call response.
  • context.response.meta.runAt: Time of call in ISO 8601 format.

To access values in request/response objects, they are keyed on their respective header/parameters keys (ex: context.response.headers.Expires). If a header/parameters contains more than one instance of a key (ex: Set-Cookie), then an array will be created on that key (ex: context.response.headers.Set-Cookie[0]). The ordering of the array will match the ordering shown on the results page of your call.


Monitor Scripts

API Science allows you to embed standard JavaScript that is executed prior to any API call. This can be done as setup to your monitor as well as in-between steps of a multi-step monitor. By using scripts you can monitor a wide variety of use cases: login sequences (such as to acquire an access token for use in subsequent calls); CRUD sequences to create, retrieve, update and delete resources in a single test flow; or to setup and re-use variables across a series of steps.
Note: Keep in mind that Monitor Scripts and Validation Scripts (see Validations reference) serve different purposes and are run in different contexts: monitor scripts aid in setup and multi-step logic prior to each API call whereas validation scripts let you run advanced test assertions against the result of any API call.

In addition to using standard JavaScript, you also have direct access to a set of libraries and functions to aid in monitoring API:
  • You can add a script to any monitor, including a single-step monitor.
  • Scripts are evaluated prior to execution of the monitor step in which they are defined.
  • You can define JavaScript variables in the Script window and use them as headers, parameters, within the URL (as part of the domain name, the query path, or parameter), or request body of your call. Each monitor has a runtime call state available through the API Science-defined global JavaScript context object. For example a script that defines a variable of myKey using:
    var context.myKey = "2340038823";
    allows you to specify a query string parameter value as {{context.myKey}}.
     
    An upcoming release of API Science will also allow you to define system-wide variables that can be used in all your tests
  • You can assign variables to the the global JavaScript context object to keep state across API calls in a multi-step monitor. For example in Step 1 you could specify
    context.user = "billg";
    and in any subsequent step's scripts access that value via context.user. That variable can also be substitued directly in parameters, headers, URL, or POST request body as {{context.user}}.
  • The context of each call response is available for use in multi-step scripts. To access the body of the previous response use:
    context.response.body
    For example to retrieve and use data from a JSON response:
    var body = JSON.parse(context.response.body);
    In this example, the body contains a JSON value of credentials.auth_token which can then be accessed and saved for use in this or subsequent steps as:
    context.token = body.credentials.auth_token;
  • By default, all the functions from the from the open source library and Underscore.js and jshashes are available including security functions such as SHA-1, Base64 and MD5.

Follow Redirects

Selecting this options will cause the monitor to automatically follow any HTTP 301 and 302 redirects.

Contacts

Email Contact
An email contact will receive alert emails to their inbox whenever an alert event has been triggered.

To setup, an email address is required.
URL Contact
A URL contact will be sent a JSON representation of an alert state whenever an alert event has been triggered. The JSON representation will match the check representation used in the API Science API.

To setup, an URL endpoint is required.
Slack Contact
A quick sentence summary of monitor status and a link to the related Check will be sent to Slack whenever an alert event has been triggered.

To setup, an a Slack Incoming Webhook URL is required. To get this URL, log into Slack and from the top left corner where your organization name is, select the arrow to reveal a drop down and further select Configure Integrations. Scroll down to the bottom of the page to the DIY Integrations & Customizations and select Incoming WebHooks. Select a chatroom or user to recieve the alerts and add the incoming webhook integration. At this point Slack will present you a Webhook URL; put in this URL for the contact on API Science to enable Slack integration.
HipChat Contact
Coming soon.
PagerDuty Contact
A quick sentence summary of monitor status and a link to the related Check will be sent your PagerDuty account whenever an alert event has been triggered.

To setup, a PagerDuty Integration Service API Key. To get this key, log into Pager data and clcik the Configuration drop down from the top bar then select Services. From this page, click the Add New Service button. From the Add a Service page, give a name to this integration and select Use our API directly for the Integration Type. After clicking the Add Service button, you will be taken to your integration overview page where a Service API Key will be presented. Use this API key for the contact on API Science to enable PagerDuty integration.