Getting Started Developing with axe DevTools Linter

This article describes how to begin using the REST API services provided by the on-premises edition of axe DevTools Linter or axe DevTools Linter SaaS. The services are provided by REST endpoints, so you need experience with a REST tool such as Postman, CocoaRestClient, or the VS Code REST Client extension. You can also access the services with a programming language such as Python.

The differences between the two editions of axe DevTools Linter (axe DevTools Linter Saas vs. the on-premises server) are that the SaaS offering requires authorization using an API with every linter request (the /lint-source endpoint).

First Steps

If you are using the SaaS edition of the axe DevTools Linter Server, you first need to obtain an API key. You can find the steps necessary to obtain the key in Obtaining an axe DevTools Linter SaaS API Key.

For the on-premises version of the axe DevTools Linter Server, you'll need to set it up (as detailed in Installing the On-Premises axe DevTools Linter Server) and then obtain the server's IP address. You'll also need the port the server is listening on (the default is port 3000).

Testing Your Connection with curl

Two of axe DevTools Linter SaaS's REST endpoints do not require authentication so you can test your connection before you obtain an API key.

If you'd like to run a simple test of whether you are able to access the server, you can use curl (or a web browser). The following curl example shows how to use the status endpoint of axe DevTools Linter SaaS:

curl https://axe-linter.deque.com/status

For the on-premises version, you'd type the following:

curl http://<server IP address>:<server port>/status

You need to replace the <server IP address> and <server port> in the above command.

If the server is available, it will respond with:

Ok

You can also visit the same URL (for example, https://axe-linter.deque.com/status) with a web browser and should see the same result.

The following example shows how to access the healthcheck endpoint:

curl https://axe-linter.deque.com/healthcheck

The server should respond with the following:

{
  "version": "4.4.0"
}

As with the status endpoint, you can also visit https://axe-linter.deque.com/healthcheck with a web browser and get the same result as with curl.

To check source for accessibility errors, you need to create a POST request. You can use curl or a tool such as Postman.

In Postman or another REST tool, you need to create a header like the one shown below:

POST https://axe-linter.deque.com/lint-source
content-type: application/json
authorization: <YOUR API KEY>

If you are using axe DevTools Linter SaaS, you need to replace with your API key. If you are using the on-premises server, you do not need to use the authorization header, but you need to change the URL to the IP and port address for your on-premises server.

With curl the equivalent header as the one shown above would be:

curl --request POST --url https://axe-linter.deque.com/lint-source \
  --header 'content-type: application/json' \
  --header 'authorization: <YOUR API KEY>'

You also need to specify a request body as a JSON object before the request is complete:

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

The complete curl command is:

curl --request POST --url https://axe-linter.deque.com/lint-source \
  --header 'content-type: application/json' \
  --header 'authorization: <YOUR API KEY>'
  --data '{ "source": "# Heading\n### Another Heading\n",
    "filename": "file.md" }'

For the on-premises server, you need to change the --url argument and remove the --header 'authorization: <YOUR API KEY>' line.

The following shows an example response to the above request:

HTTP/1.1 200 OK
Date: Mon, 14 Mar 2022 14:04:19 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 419
Connection: close
X-Powered-By: Express
Surrogate-Control: no-store
Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
Pragma: no-cache
Expires: 0
ETag: W/"1a3-cfgZ30xjvW815mLDpbjoGXreu2o"

{
  "report": {
    "errors": [
      {
        "ruleId": "heading-order",
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/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
      }
    ]
  }
}

Because this example has an accessibility issue, you received a response that contains a report object containing an errors array of error objects. See Response for more information about this response object.

If your API key doesn't exist when you use axe DevTools Linter SaaS, you'll receive a response like this:

HTTP/1.1 404 Not Found
Date: Fri, 11 Mar 2022 22:38:51 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 33
Connection: close
X-Powered-By: Express
Surrogate-Control: no-store
Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
Pragma: no-cache
Expires: 0
ETag: W/"21-HAVNeHb+a8RfOcMl419aKM67S20"

{
  "error": "No API key found"
}

In this case, you can try recreating your API key or contacting the Deque Help Desk for help.

See Also

• See Getting an API Key for the steps needed to get an API key necessary to use axe DevTools Linter SaaS.
• See axe DevTools Linter Server REST API Reference for a reference to the APIs provided by axe DevTools Linter Server as well as additional options for the linter-source endpoint.
• The axe DevTools Linter REST API Example Usage contains a curl example and a Python example that you can use with axe DevTools Linter Server.