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
|
| 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: |
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 |
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"] ] }] } } }
|