QA2L API Documentation

Introduction:

The QA2L API v1.0 can be used to perform on demand validation of page resources from an external application.

It can also be used to retrieve the current status of all scheduled QA tasks belonging to a specific user and display that status in external applications.

To use the API you would need to obtain a secret key. Authenticated users can generate an API secret string via the ... > My Account > Preferences page. 

Basic Usage:

To call the QA2L API, use the URL:

https://www.qa2l.com:3003/1.0/




While HTTPS is recommended, you can also access the QA2L API at:

http://www.qa2l.com:3000/1.0/

 



GET | POST: https://www.qa2l.com:3003/1.0/

Returns a JSON object containing information about the API version, and basic information about valid endpoints and parameters.

Sample Response:

{

name: 'QA2L API',

version: '1.0',

endpoints: [

{ path: '/tags',

parameters: [

{ name: 'url', value: 'http(s)://page (required)' },

{ name: 'include', value: 'Adobe Analytics, Google Analytics, etc. (optional)' },

{ name: 'match', value: 'string1,string2,... or <regex> (optional)' },

{ name: 'stealth', value: 'true|yes|y|1 (optional) (default is false)' },

{ name: 'header', value: 'X-Vendor: My-Custom-Vendor-Header (optional)' },

]

},

{ path: '/tasks' ,

parameters: [

{ name: verbose, value: 'true|yes|y|1 (optional) (default is false)' }

]

},

(...)

]

}


GET | POST: https://www.qa2l.com:3003/1.0/tags

Returns a JSON object containing information about analytics calls made by a page whose URL you have provided in the request.

Parameter Description
url
required
The complete URL of the page you want to collect analytics tags, including http(s) and any query parameters. If using GET, ensure the url parameter value is encoded.
   
stealth
optional
Use &stealth=true|yes|on|1 to block outgoing analytics requests from leaving the page. Default value is false (analytics calls will not be blocked from going out).
   
include
optional
Comma-separated list of analytics vendors to include. By default, the method returns all analytics tags found on the page. For a list of friendly vendor names, call the /tags method on a URL without the include parameter to see all vendors detected on the page.

Example:

https://www.qa2l.com:3003/1.0/tags?secret=XYZ&url=http://www.mysite.com&include=Adobe Analytics,BlueKai

Note: This parameter is case-insensitive and allows for loose matching (e. g. "google" returns all vendor calls related to Google).

   
match
optional

Comma-separated list of strings to match in a page resource URL. Loading a web page can be time-consuming for a number of reasons. If you are only interested in a particular vendor/parameter, or if you just want to check whether a specific resource has loaded on the page, you can tell us to return the results as soon as a resource has been seen. This parameter overrides the ‘include’ parameter and can be used to validate any request, not just Analytics vendor calls.

Example:

https://www.qa2l.com:3003/1.0/tags?secret=XYZ&url=http://www.mysite.com&match=b/ss,v0,my_campaign_id

Note: By default this parameter is case-sensitive. You can optionally change this using RegEx as shown in the example below:

  • match=<AbCdEfg>i
Additional RegEx logic can be included to allow different more advanced match patterns, example:

  • match=<b/ss/.*v0.*AbCdEfg>i
   
links 
optional

true|yes|y|on|1. Retrieve any links that may be on the page when setting this parameter. Default is false.

   
exists 
optional

true|yes|y|on|1. Check if the URL exists when setting this parameter. If the URL exists, the API will return the HTTP status code. If the URL does not exist, the API returns:

"error":true,"message":"ENOTFOUND"

Default is false.

   
headers 
optional

Allows you to set the HTTP header for the request, example:

&header=authorization:%20Basic%20Z3Vlc3Q6Z3Vlc3Q=


GET | POST: https://www.qa2l.com:3003/1.0/tasks

Returns a JSON array of objects. Each object is a task owned by the QA2L user calling the API (as determined by the secret string).

 

Parameter Description
verbose 
optional
true|yes|y|on|1. Specify whether to include the last status report in HTML format. This may result in very large output. Default is false.
   
id 
optional
Retrieve the details of a single task. The response is an array with a single object, or an empty array if the task is not found (or the user lacks permission to see it). If used in conjunction with "run", this parameter can accept a single task id, or a comma-separated list of task id's.

   
run 
optional
true|yes|y|on|1 Schedules one or more tasks to run in the next available time slot. This parameter overrides any existing scheduling for the task and is a shortcut for setting "next" to current date, "hour" to current hour, "enabled" to "false" and frequency to "once". Use the id parameter to specify which tasks to run. The request returns a subset of tasks with their new scheduled run time displayed. Any task results are distributed based on the individual task settings when they complete.

Sample Task Object:

Parameter Description

{

"id": 451,
"name": "My task",
"steps": 4,
"param": {
"type": "flow",
"include screenshots": 1,
"notify on success": 0,
"stealth mode": 0,
"frequency": "daily",
"hour": "4 AM",
"cc": "jon@smith.com",
"bcc": "jon@smith.com",
"ua": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36",
"width": "1160",
"crawl": 0,
"enabled": 0
},
"last_run": null,
"result": "Success",
"createdAt": "2016-12-02T03:58:02.000Z"

}

 

GET | POST: https://www.qa2l.com:3003/1.0/task

Returns a detailed JSON object for a single task which includes an array of history objects. Each object in the history array is a result of a task run containing the validation results for all parameters specified during design.

Query Parameters:

Parameter Description
id 
required
Retrieve the results of runs for a specified task id. Task id's can be obtained by first using the /tasks endpoint.

   
format 
optional
json|csv. Retrieve the details of a single task in either json or csv format. The default value is json.

   
limit 
optional
Retrieve the results of scheduled and ad-hoc runs for a particular task. Results are in descending order (most recent run first). Default value is 12. Max value is 100.
   
mode 
optional
scheduled|ad-hoc|both. Specify which type of task runs you want to return. Default value is both.
   
run 
optional
true|yes|y|1 - Schedules one or more tasks to run in the next available time slot. This parameter overrides any existing scheduling for the task and is a shortcut for setting "next" to current date, "hour" to current hour, "enabled" to "false" and frequency to "once". The request returns the task with its new scheduled run time displayed. Can be used together with a POST task update object (see below).
   

task
optional

POST method only. Content-Type "application/json" header should be set. For Publisher and above, this payload updates most task parameters and can also be used to alter the checks defined at all existing task steps. Not all parameters can be modified. Any malformed or unsupported key-value pairs are ignored. The updated task object is returned in the response. Can be used together with the run parameter to kick off the task as soon as possible.

Sample Task Response:

JSON

{

"id": 790,
"name": "API Uptime",
"param": {
    "enabled": 1,
    "type": "flow",
    "hour": "5 AM",
    "next": "5/5/2017",
    "stealth mode": 1,
    "notify on success": 0,
    "include screenshots": 1,
    "jserr": 0,
    "cc": "",
    "bcc": "",
    "width": "1160",
    "ua": "Mozilla/5.0 (Windows NT 10.0; WOW64; rv:48.0) Gecko/20100101 Firefox/48.0",
    "before": [
    ],
    "frequency": "hourly",
    "tolerate": [
    "jserr"
     ],
    "url": null,
    "crawl": 20
},
"history": [
    {
        "steps": [
            {
               "type": "open",
               "url": "https://www.qa2l.com:3003/1.0/tags?secret=123&url=http://...",
               "checks": [
                  {
                      "id": "191",
                      "name": "QA2L",
                      "global": 0,
                      "params": [
                          [
                             "[tracking call]",
                             "contains",
                             "/qa2l/track",
                             {
                                "type": "success",
                                "val": "OK"
                             }
                          ],
                          [
                             "event",
                             "equals",
                             "page load",
                             {
                                "type": "success",
                                "val": "OK"
                             }
                          ],

                          .........
                       ]
                    }
                ]
            }
        ],
     "time": "2017-05-05T04:00:50.000Z",
     "type": "scheduled",
     "result": "Success"
   }

   (...)
]

}



Sample Task Update Body:

JSON

"task": {

"name": "New Task Name",
"param": {
    "enabled": 1,
    "hour": "5 AM",
    "next": "5/5/2017",
    "width": "1160",
    "frequency": "hourly",
    "crawl": 20 /* if task is an audit or scan, this is the page limit */
},
"steps": { /* array also accepted if you don't want to identify any steps by name */
    "on homepage load": {
         "checks": [{
              "name": "Google Analytics",
              "params": [
                  ["dt", "equals", "Home"]
              ]
         }]
    },
    "2": { /* you may use numeric index if step has no name */
         "name": "after login" /* renames step #2 */
         "checks": [{
              "name": "Google Analytics",
              "params": [
                  ["dt", "equals", "Your Account"]
              ]
         }]
    }
}
}