Documentation

All Topics

Testing raw HTML Content for Accessibility Violations

  • Issue an HTTP POST request to the ODA API request endpoint: https://api.oda-api.com
  • Include with this request your API Key in the X-API-Key header. E.g. X-API-Key: <your-api-key-goes-here>
  • Include a JSON payload of the form: 
                                            
    {
        "content": "<html>...</html>"
    }

    Remember to escape your HTML content as JSON

Testing HTML Content Located at a Specific URL

  • Issue an HTTP POST request to the ODA API request endpoint: https://api.oda-api.com
  • Include with this request your API Key in the X-API-Key header. E.g. X-API-Key: <your-api-key-goes-here>
  • Include a JSON payload of the form: 
                                            
    {
        "url": "https://www.exampleurl.com/mypage.html"
    }

Testing HTML Snippets

Note that when testing HTML snippets, page-level accessibility checks are disabled to eliminate confusion. For example, certain checks for valid page landmarks are disabled since a snippet could live inside an HTML hierarchy that has valid landmarks.

  • Issue an HTTP POST request to the ODA API request endpoint: https://api.oda-api.com
  • Include with this request your API Key in the X-API-Key header. E.g. X-API-Key: <your-api-key-goes-here>
  • Include a JSON payload of the form: 
                                            
    {
        "content": "<div><p>This is my snippet</p></div>",
        "snippet": true
    }

    Remember to escape your HTML content as JSON

Testing Using a Callback URL

Large pages can take a non-trivial (> 30 seconds) amount of time to process. The callback flow allows you to make requests that will respond immediately but will POST results of accessibility checks to the specified callback URL once processing has completed. If you are experiencing timeouts using the normal synchronous request flow (i.e. without a callback URL), try using a callback URL. The callback URL must be publicly accessible and should be expecting HTTP POST requests containing JSON.

  • Issue an HTTP POST request to the ODA API request endpoint: https://api.oda-api.com
  • Include with this request your API Key in the X-API-Key header. E.g. X-API-Key: <your-api-key-goes-here>
  • Include a JSON payload of the form: 
                                            
    {
        "url": "https://www.mywebsite.com",
        "callback": "https://www.mywebsite.com/callback"
    }

    Note that you can use url or content parameters when supplying a callback URL

  • The immediate response you will receive will look like: 
                                            
    {
        "success": true,
        "message": "Results will be posted to callback URL"
    }
  • The results POSTed to the callback URL will look the same as the results you would receive from the synchronous request flow.

Waiting for an Element to Be Present Before Testing

Due to the dynamic nature of many websites, it is often desired that automated testing tools wait until a particular element or elements be present in a page before testing commences. In order to achieve this using ODA API, you can simply use the waitForElement parameter.

This parameter takes a standard CSS selector as its value. When specified, the testing engine will wait up to 5 seconds for an element matching the selector to be present in the page before running accessibility checks. If the element cannot be found after 5 seconds, then an error will be returned. See below for a complete list of request flow instructions when using this parameter.

Note that the waitForElement parameter is not currently supported when the snippet parameter is true.

  • Issue an HTTP POST request to the ODA API request endpoint: https://api.oda-api.com
  • Include with this request your API Key in the X-API-Key header. E.g. X-API-Key: <your-api-key-goes-here>
  • Include a JSON payload of the form: 
                                            
    {
        "url": "https://www.mywebsite.com",
        "waitForElement": "#divContainingElementToWaitFor .elementToWaitFor"
    }

Testing a Site

Testing a Site involves detecting URLs in the Site's content and then testing those discovered URLs for accessibility violations. After a URL is tested, the test result is POSTed to the callback provided by the user. A callback parameter is required for these types of API calls as they can take a long time to process.

  • Issue an HTTP POST request to the ODA API request endpoint: https://api.oda-api.com/scan (note the /scan sub-path)
  • Include with this request your API Key in the X-API-Key header. E.g. X-API-Key: <your-api-key-goes-here>
  • Include a JSON payload of the form: 
                                            
    {
        "url": "https://www.mywebsite.com",
        "callback": "https://www.mywebsite.com/callback"
    }
  • The immediate response you will receive will look like: 
                                            
    {
        "success": true,
        "message": "Scan for site 'https://www.mywebsite.com' has commenced. Results will be posted to 'callback' URL."
    }
  • The results POSTed to the callback URL will look the same as the results you would receive from the synchronous request flow.

Detection Modes

Sitemaps

If your site has a valid robots.txt file located at the root of the site and it contains one or more Sitemap declarations, then URLs contained in those sitemaps will serve as the source for the site scan. This method for scanning a site is the most reliable and efficient as it allows the site owner to be explicit about which URLs should be tested and does not require that the site be manually crawled to detect URLs. Note that any rules declared for the * User-Agent in robots.txt will be followed when scanning a site.

Manual Crawl

If no Sitemaps are found, the second mode manually crawls the site starting at the initial url provided in the API request. Any links detected in that page and any subsequent pages that are in the same domain (exact match) will be crawled until no new unique URLs can be found. This method is not enabled by default; you must include an additional parameter in the initial request, allowManualCrawl, and set its value to true for this method to be considered. This mode will ignore the following types of links:

  • Links with well-known file extensions (e.g. .pdf, .jpg) that do not refer to html pages
  • mailto:, javascript:, file:, and ftp: links
  • Links excluded by rules declared in robots.txt for the * User-Agent
  • Links to anchors (e.g. https://www.oda-api.com#documentation) unless the URL preceding the anchor is unique and has not been crawled yet
  • Duplicate links

A site scan will always attempt to use the sitemap mode first even if the allowManualCrawl parameter is set to true. However, if the sitemap method fails, the scanning process will proceed with a manual crawl.

Each accessibility request generated as part of a site scan counts as a single normal API request. So for example, if the system detects 500 page URLs in your site, 500 accessibility testing requests will be generated and those will be included in your monthly usage.

Handling Common Error Codes

Below are the most common HTTP error codes you might receive as a response from ODA API and the best way to handle them.

413: Payload Too Large

The maximum payload size for an ODA API request is 6MB. If you exceed this limit then you will receive a 413 response code. This can be addressed by gzip-ing the request payload and including an additional HTTP header, X-ODA-Compression, in your request along with updating the Content-Type header. The X-ODA-Compression header should look like X-ODA-Compression: gzip and the Content-Type header should look like Content-Type: application/octet-stream.

Most modern programming languages come equipped with a library/utility that will gzip data for you which should make for an easy task. However, do not base64 encode your gzipped payload as doing so will result in an error.

Note that sending large payloads (gzipped or not) using the synchronous request flow can result in 504 errors.

429: Too Many Requests

Every API Key is limited to a maximum number of requests per month and maximum number of concurrent requests. When either of these limits has been reached, you will receive a 429 response. It is more likely to reach the maximum number of requests per second than the monthly maximum. In general, when you receive a 429, you should use an exponential backoff mechanism to retry the request. So, for example after receiving your first 429, wait 2 seconds and retry and then after the second 429 in a row, wait 4 seconds and then retry, etc.

If after using exponential backoff every request you send is still resulting in a 429, then either you have reached your monthly maximum or there is some other system that is making requests using the same API Key that you are currently using; and the total volume of requests is too high. To determine if you have reached your monthly maximum, see Checking Monthly Usage below. If you have not and there are no other scripts/applications using the same API Key, please contact support.

504: Gateway Timeout

A gateway timeout occurs when a request has taken too long to process. This usually occurs when you have sent a large request payload to the API and you are using the synchronous request flow. The maximum amount of time a request can take is 30 seconds and once that limit is reached you will receive a 504.

To remedy this error, you should use a callback url which will wait in the background up to 5 minutes for the request to complete.

Other 50x Errors
Other 50x errors will generally be accompanied by a specific error message in the body of the response which will help you rectify the problem. These errors usually indicate that the API encountered an unexpected error while attempting to check your content for accessibility violations.

Checking Monthly Usage For Your API Key

Note that there is some delay between when requests are made and when they are included in your usage.

  • Issue an HTTP GET request to the ODA API request endpoint: https://api.oda-api.com/usage
  • Include with this request your API Key in the X-API-Key header. E.g. X-API-Key: <your-api-key-goes-here>
  • The response will look like: 
                                            
    {
        "usage": 126,
        "remaining": 874
    }