The axe DevTools Linter REST API Reference

axe DevTools Linter allows you to check code for accessibility problems using a REST API. You create an HTTP request object that contains the source lines you would like checked (in the body of the request as a JSON object), and the server returns a response JSON object that indicates any accessibility problems that the server finds.

The server can check React (.js, .jsx, .ts, and .tsx), Vue (.vue), Angular (.component.html), HTML (.html and .htm), and Markdown (.md and .markdown) files.

The REST Endpoints

There are six REST endpoints provided by the server. The first endpoint (/lint-source) responds to POST requests and checks your code for accessibility issues. The second endpoint (/status) responds to GET requests and shows whether the server is available with a 200 response code indicating the server is listening. The third endpoint (/healthcheck) responds to GET requests and indicates whether the server is running and returns the version number of the running server. The remaining three endpoints allow SaaS edition users to obtain usage information for their enterprise as a whole (/billing/enterprise), their users (/billing/user), and their API keys (/billing/key).

The REST endpoints are as follows:

The Lint Endpoint (/lint-source)

The lint endpoint is the main service endpoint, and you can use it to send code to axe DevTools Linter to check for accessibility issues. It accepts POST requests with a JSON body containing the code to be checked.

Request

To use this endpoint, you create a POST request to the server's lint endpoint as shown in the example below:

POST /lint-source

You also need to include a Content-Type header to tell the server that the body of the request contains a JSON object.

Content-Type: application/json

If you are using axe DevTools Linter SaaS, you will need to include an authorization header with your API key, as shown below:

Authorization: <YOUR API KEY>

You can find out more about obtaining an API key in Obtaining an axe DevTools Linter SaaS API Key.

The body of the request should contain the code (inside a JSON object) that you would like to check. For example, the following JSON object checks a markdown sample:

{
  "source": "# heading\n### Another heading\n",
  "filename": "file.md"
}

The above Markdown sample has an accessibility error: the heading levels have a gap between the first heading (heading level 1) and the second heading (heading level 3). To see the server's response to this error, see the Response section below.

The JSON Request Object

The following table shows the properties used with the JSON request object:

The source string in the request JSON object is the code that you'd like to check. You need to escape all quotes and newlines (precede with a backslash).

The language string can take one of the following values:

The server uses the filename and language properties to figure out which linter to use. Usually, axe DevTools Linter will use the file extension on the filename property to choose the linter. If you'd like to specify explicitly the linter to use instead, you can use the language property and the values specified in the table above. In this case, you must still specify a filename as it is a required parameter, but language takes precedent over the filename's extension. For example, if you specify a filename of "somefile.html" and a language of md the server will use the Markdown linter.

Response

The server responds with a response code of 200 whether or not there are any accessibility errors. You need to examine the JSON in the body of the response to see if there are errors.

If the code has no errors, the JSON response object is as follows:

{
  "report": {
    "errors": []
  }
}

The following example shows the response JSON object for source that has an error (note that errors is an array of error objects).

{
  "report": {
    "errors": [
      {
        "ruleId": "heading-order",
        "helpURL": "https://dequeuniversity.com/rules/axe/4.3/heading-order?application=axe-linter",
        "description": "Ensures the order of headings is semantically correct",
        "lineContent": "### Another heading",
        "lineNumber": 2,
        "linterType": "md",
        "column": 1,
        "endColumn": 20
      }
    ]
  }
}

The error Object

The errors array holds error objects, which have the following properties:

The config Object

You can specify a config property if you would like more control over the rules that axe DevTools Linter uses to check your source for accessibility errors.

{
  "source": "<html></html>",
  "filename": "file.html",
  "config": {
    "rules": {
      "html-has-lang": false
    },
    "exclude": [],
    "tags": []
  }
}

The previous example shows that, although the source has an accessibility error (a missing lang attribute on the html element), no errors will be returned because that rule has been turned off.

The global-components Object

The global-components object maps custom components and their attributes to existing HTML elements and attributes. For introductory information on linting custom components, see Linting Custom Components.

The following example shows a complete custom component mapping:

{
  "config": {
    "global-components": {
      "custom-component": {
        "element": "html-element",
        "attributes": [
          { "custom-attribute-1": "html-element-attribute-1" },
          { "custom-attribute-2": "<text>" },
          "aria-*"
        ],
        "replace": true
    }
  }
}

The example shows the mapping from the custom component custom-component to html-element with attributes custom-attribute-1 mapped to html-element-attribute1 and custom-attribute-2 mapped to <text>, which is a special attribute value that maps custom-attribute-2 to the text content of the output HTML element. For more information, see The Special <text> Value.

The special aria-* value indicates that all ARIA attributes on the custom element should be copied to the output HTML element. See Using aria-* for more information.

The replace property indicates whether custom-component should be removed from the output DOM tree, which Angular and JavaScript custom elements include. The default value is false.

If the custom component doesn't require attribute mapping, you can use this abbreviated format that maps custom-component to html-element:

{
  "config": {
    "global-components": {
      "custom-component": "html-element"
    }
  }
}

The rules Property

The rules property references a LinterRuleset object, which allows you to enable or disable rules by their rule ID. For more information about the accessibility rules, see axe DevTools Linter Accessibility Rules.

For example, the following configuration enables the image-alt rule and disables the tabindex rule:

{
  "config": {
    "rules": {
      "image-alt": true,
      "tabindex": false
    }
  }
}

For a list of rules that the server checks against, see axe DevTools Linter Accessibility Rules

The exclude Property

axe DevTools Linter does not use the exclude property. It is used by axe DevTools Linter Connector's configuration to exclude files from linting. See Configuration File in the documentation for axe DevTools Linter Connector for more information.

The tags Property

The tags property is an array of strings or tags. Each tag is attached to one or more accessibility rules, so by specifying multiple tags here, you can enable many different accessibility rules (and disable any rules that are not tagged with the specified tags). The tags typically correspond to different accessibility standards, and each rule can be a member of many different tags.

The Status Endpoint (/status)

To receive the server's status, send a GET request to the server's status endpoint. The example below shows a status request:

GET /status

If the server is running, it will respond with the following response (and a 200 response code):

Ok

The Health Check Endpoint (/healthcheck)

To check whether the server is running and return its version number, send a GET request to the health check endpoint. An example request is shown below:

GET /healthcheck

If the server is running, it will respond with the version number of the server, as shown in the example below:

{
  "version": "4.4.1"
}

The Enterprise Billing Endpoint (/billing/enterprise)

The enterprise billing endpoint allows you to obtain total usage information for your enterprise and the usage broken down by individual API keys. The endpoint responds to a GET request and requires you to specify a year and month (here May 2022), as shown below:

GET https://axe-linter.deque.com/billing/enterprise/2022/4
authorization: <YOUR-API-KEY>

The request requires an authorization header with your API key. See Obtaining an API Key for more information.

By default the server returns one month of data, but you can use the optional months= query string to specify more. The months parameter can range from 1 to 12 (inclusive). The example below shows an example of obtaining three months of data starting with May 2022:

GET https://axe-linter.deque.com/billing/enterprise/2022/4?months=3
authorization: <YOUR-API-KEY>

Response

The SaaS linter server responds with JSON object which contains two objects. The first is a summary object and the second, api_keys, is an collection of objects that contain information about each API key's usage of the linter service.

An example response object is shown below:

{
   "summary": {
      "year": 2022,
      "month": 5,
      "total_lines_linted": 500,
      "total_scans": 40
   },
   "api_keys": [{
      "id": "a2fd58d0-4810-4fbb-b928-7befa01bf89c",
      "name": "My Project",
      "keycloak_id": "d117bb33-1308-41b0-8960-06301eefb169",
      "user_email": "someone@example.com",
      "total_lines_linted": 500,
      "total_scans": 40
   }]
}

The summary Object

The summary object gives you information about the total number of lines linted and how many scans were initiated by users within the enterprise.

The api_keys Array

The api_keys array contains objects comprised of the following properties:

The User Billing Endpoint (/billing/user)

This endpoint, the usage billing endpoint, allows you to obtain billing information for a user for all API keys used to access the SaaS server. The default is for one month's data to be returned.

The following example shows a request for May 2022 for the user represented by the provided API key (in the authorization header):

GET https://axe-linter.deque.com/billing/user/2022/4
authorization: <YOUR-API-KEY>

Like the other billing endpoints, you can specify an optional months query string as shown below:

GET https://axe-linter.deque.com/billing/user/2022/4?months=2
authorization: <YOUR-API-KEY>

The following shows an example response object:

{
   "summary": {
      "year": 2022,
      "month": 5,
      "total_lines_linted": 500,
      "total_scans": 40
   },
   "api_keys": [{
      "id": "a2fd58d0-4810-4fbb-b928-7befa01bf89c",
      "name": "My Project",
      "keycloak_id": "d117bb33-1308-41b0-8960-06301eefb169",
      "user_email": "someone@example.com",
      "total_lines_linted": 500,
      "total_scans": 40
   }]
}

The response object contains two objects, summary and api_keys belonging to the user. For more information see The summary Object and The api_keys Array above.

The API Key Billing Endpoint (/billing/key)

To obtain usage data for an API key, you can use the API key billing endpoint. You need to specify the year and month as shown below:

GET https://axe-linter.deque.com/billing/key/2022/4
authorization: <YOUR-API-KEY>

Like the other billing endpoints, you can specify an optional months query string as shown below:

GET https://axe-linter.deque.com/billing/key/2022/4?months=2
authorization: <YOUR-API-KEY>

An example response object is shown below:

{
  "name": "My Project",
  "total_lines_linted": 1000,
  "total_scans": 200
}

The name value is the name that was assigned to the API key when it was created. The other values total_lines_linted and total_scans specify the number of lines that were linted in the time period specified when the API was called and the total number of scans that were initiated by this API key in the time period specified.

URL Quick Reference

Important URLs for use with axe DevTools Linter SaaS are as follows:

See Obtaining an axe DevTools Linter SaaS API Key for more information about the steps required to obtain an API key.