Understanding Tenon API Request Parameters

Either the url or src are required for testing. The URL must be a fully qualified URL that the API has access to. If any GET parameters are required in order to access the URL, you must supply them as part of the URL. If using src it must be a string of document source only (HTML, CSS, and JavaScript).

Supplying both url and src, beyond being plain silly, will result in only the URL being tested.

When supplying src, this can be anything ranging from the source of a complete document or only a fragment of a document (mark this case using the fragment parameter, described below). The src is preferable when testing something that is otherwise not available via URL.

Sometimes accessibility tools will return results that the tool isn't completely sure is a real issue. The certainty parameter allows you to filter out these "uncertain" results by choosing a minimum acceptable certainty score.

• Valid values: must be one of '0','20','40','60','80','100'
• The default value is '0', meaning that the minimum certainty score for issues returned is '0'

Note: You probably don't want to only choose '100' as this will, in practice, probably be too conservative. We try to create tests that return real results and so very low certainty scores should be few and far between. As a general guide, if integrating Tenon into an automated build or pre-commit hook, use 80 and above. For a QA scenario, choose the lowest value you can tolerate as an organization.

The projectID parameter is a string of text you can supply to identify the tested document as part of a specific system. This can (and should) be used in conjunction with the reportID parameter so that you can identify your request as being part of a test effort (a report) on a specific system. This is especially useful if you are developing or testing multiple projects.

• Valid values: can be any arbitrary alphanumeric string up to 255 characters in length.

Note: it is your responsibility to ensure accuracy and validity of the supplied string. We will accept any (safe) arbitrary string for this parameter. If no value is supplied, the report will go into your default system

The docID parameter is a string of text used to identify the page being tested. This can be used by you to track the performance of a specific page. Although this can also be done via the URL, you can also use this when testing document source, for which there is no useful URL.

• Valid values: If supplied, can be any arbitrary alphanumeric string between 16 and 255 characters in length. It must be an unbroken string (In other words it must not contain spaces). The only punctuation allowed is '-' and '_'
• If your request does not contain a docID, we will generate a GUID formatted string for the docID.

Each Best Practice in the system has a number of factors that allow us to determine their relative priority. In your result set, each issue reported will be given a calculated priority score which you can then use to filter or order your results.

• Valid values: must be one of '0','20','40','60','80','100'
• Default value will be '0'. As a consequence all issues, regardless of Priority, will be reported.

Note: in practice, it is unlikely that an issue returned will have 100% priority. Like certainty, you should supply the lowest priority you can, especially when first starting out. Setting this too high may result in no errors returned.

The level parameter indicates the "lowest" WCAG level to test against.

• Valid values: must be one of 'A','AA','AAA'. Chosing "AA", for instance, will test both "AA" and "A" success criteria.
• Default value is 'AAA', meaning that all tests for AAA, AA, and A will be run.

Note: Keep in mind that WCAG Level does not actually correlate to Priority when determining what to test for. For more information on our philosophy regarding prioritization, see blog post by Karl Groves: Understanding WCAG Level

In practice, very few of the Level AAA Success Criteria are testable using automated means and therefore you'll see few tests against these anyway. Despite this, we recommend selecting "AAA" for the level parameter and being more stringent in your certainty setting, because it is likely that doing so will have a greater impact against False Positives than filtering by Level.

• Value supplied muse be numeric string only
• Value should be supplied in milliseconds. In other words, '1000' is 1 second, '2000' is 2 seconds, etc.
• Setting this value too high may result in a request timeout from the API

The fragment parameter only works when submitting content to the API via the src attribute. Using fragment when testing an url will be ignored. This parameter allows you to identify the source string as only a fragment of a page. This will essentially filter out the reporting of document-level issues and return results relevant only to the source fragment you submit.

• Valid values: must be one of '0','1' representing false and true.
• The default value is '0'

Note: do not set fragment to '1' if you're sending over a complete document. You will get weird results.

The store parameter indicates whether or not Tenon should store your results. You can then come back later and view your results in our Web-based system.

• Valid values: must be one of '0','1' representing 'false' and 'true'.
• Default value is '0', meaning that we will not store the results.
• If you set this to '1' you can later retrieve the stored results by using the URL pattern: https://tenon.io/history.php?responseID=[xxx] where the value for the 'responseID' parameter is the value returned in the response

Note: The length of time we will store the results depends upon your plan.

The uaString parameter allows you to supply any arbitrary string of text which will be sent as the User-Agent string when we request the URL you supply. This is particularly useful if your site does any user-agent sniffing.

• Valid values: can be any arbitrary string up to 255 characters in length.

Note: it is your responsibility to ensure accuracy and validity of the supplied string. We will accept any (safe) arbitrary string for this parameter. If no value is supplied, Tenon identifies itself with a Google Chrome user-agent string.

The viewPortHeight parameter sets the height, in pixels, of the viewport for our headless browser.

• Valid values: must be a string consisting only of numeric characters, no more than four characters in length. In other words, it can be any positive number between 0 and 9999.

Note: If this parameter it is not supplied at time of request it will be set to '768'. If you set one viewport parameter you must set both

The viewPortWidth parameter sets the width, in pixels, of the viewport for our headless browser. This parameter is particularly useful when testing the accessibility of your responsive design.

• Valid values: must be a string consisting only of numeric characters, no more than four characters in length. In other words, it can be any positive number between 0 and 9999.

Note: If this parameter it is not supplied at time of request it will be set to '1024'. If you set one viewport parameter you must set both