Integrating Axe Developer Hub with CI/CD platforms

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

Use Axe Developer Hub's REST web service with various Git platforms

Not for use with personal data

Requires:

Your web project uses Git data

Axe Developer Hub Project ID

Deque API Key corresponding to your project type

Overview

Axe Developer Hub provides a REST web service that you can use as a basis for integration into your CI/CD implementations with services such as GitLab and BitBucket. If you are using GitHub, please see Using the Axe Developer Hub GitHub Action.

The REST service expects as input an Axe Developer Hub API key, your project ID, and a Git commit SHA. Within the response object you'll see:

The number of accessibility errors found during the last test run
The number of accessibility errors over the a11y threshold
A URL directing to detailed results on Axe Developer Hub

Retrieve Test Run Information

The web service responds to a GET request and can retrieve information about a particular Git commit SHA for the specified Developer Hub project.

GET https://axe.deque.com/api-pub/v1/axe-watcher/gh/<:SHA>?project_id=<your-project-id>

Requirements

Your request will require one path parameter, a query parameter, and two headers.

Server: https://axe.deque.com
Endpoint: /api-pub/v1/axe-watcher/gh/<*:SHA*>
Query parameter: ?project_id=<your-project-id>
Request method: GET

Path Parameter: The :SHA parameter should be replaced with the Git commit SHA you want to examine.

Query Parameter: Replace '' with the unique project ID that appears on the instructions page after you create a project. To find this information at any point after setup, go to your Projects in Axe Developer Hub. Find your project, go to its Settings, then select Configure project to open the instructions page.

Headers: Two headers are required:

Accept: application/json
X-API-Key:<your-personal-api-key>

Example Request:

GET https://axe.deque.com/api-pub/v1/axe-watcher/gh/9eabf5b536662000f79978c4d1b6e4eff5c8d785?project_id=268a7e7d-cb23-45a0-aa7d-6f35e3bed2c9

(Headers are required but not shown.)

Response JSON

The following shows an example JSON response body returned from the service:

{
  "project_name": "Main test suite",
  "issues_over_a11y_threshold": 2,
  "last_run_created_at": "2024-01-21T17:16:39.267Z",
  "last_run_violation_count": 2,
  "last_run_new_violation_count": 2,
  "last_run_resolved_violation_count": 0,
  "last_run_page_state_count": 2,
  "difference_in_page_states": 0,
  "axe_url": "/axe-watcher/projects/19f12525-bcbe-4b4f-9b12-76de4f375d9b/branches/test-updates/compare/353ec943-b957-4abc-8d3a-5deed182a304/9288e977-b81f-49d7-83de-010255baede4?settings_hash=bc8334022f94bb2d9f69447946df487f&issues_over_a11y_threshold=2"
}

The following table provides information about the values in the JSON response:

Item	Type	Description
`axe_url`	`string`	The absolute path of these results on Axe Developer Hub
`difference_in_page_states`	`number`	Numerical difference in page states compared to previous commit on the same branch
`issues_over_a11y_threshold`	`number`	Count of issues that exceed the a11y threshold
`last_run_created_at`	`string`	Date and time in ISO 8601 format, UTC timezone, millisecond granularity, of the test run
`last_run_new_violation_count`	`number`	Count of new accessibility errors
`last_run_page_state_count`	`number`	Count of page states
`last_run_resolved_violation_count`	`number`	Count of accessibility issues that were resolved since the previous commit on this branch
`last_run_violation_count`	`number`	Count of accessibility errors
`project_name`	`string`	The name of the project as shown on the Projects page in Axe Developer Hub

Error Responses

Status	Cause	Response Body
`404 Not Found`	SHA not found, or no test run associated with it	`{ "error": "No Git information found" }`
`401 Unauthorized`	Invalid API key	`{ "error": "Invalid API key" }`

Usage Examples

The following examples show how to access the REST endpoint. In each example, you need to set the required parameters as environment variables:

Environment variable	Description
`API_KEY`	A personal API key corresponding to your project type (found on the Axe account page )
`PROJECT_ID`	Your unique project ID
`GIT_SHA`	The Git commit SHA for which you'd like to obtain Axe Developer Hub results

JavaScript (Node.js)

This example requests Axe Developer Hub results for the specified SHA (in the GIT_SHA environment variable) and specified project ID. If new accessibility errors are discover, the count is logged to the console. Otherwise, 'axe clean!' is logged to the console.

note

This exmaple does not test for errors such as an invalid API key or missing Git information.

const https = require('https')
const assert = require('assert')

const { API_KEY, PROJECT_ID, GIT_SHA } = process.env
assert(API_KEY, 'API_KEY is required')
assert(PROJECT_ID, 'PROJECT_ID is required')
assert(GIT_SHA, 'GIT_SHA is required')

const request = () =>
  new Promise((resolve, reject) => {
    /** @type {import('http').RequestOptions} */
    const options = {
      hostname: 'axe.deque.com',
      port: 443,
      path: `/api-pub/v1/axe-watcher/gh/${GIT_SHA}?project_id=${PROJECT_ID}`,
      method: 'GET',
      headers: {
        'X-API-Key': API_KEY,
        Accept: 'application/json'
      }
    }

    let data = ''

    const req = https.request(options, res => {
      res.on('error', reject)

      res.on('data', d => {
        data += d
      })

      res.on('end', () => {
        const json = JSON.parse(data)
        resolve(json)
      })
    })
    req.end()
  })

const main = async () => {
  let json = null
  for (let tries = 0; tries < 10; tries++) {
    try {
      json = await request()
      break
    } catch (err) {
      console.warn(err.message)
    }
  }

  assert(json, 'Unable to fetch data from axe.deque.com')

  const { last_run_violation_count, axe_url, project_name, issues_over_a11y_threshold } = json

  if (last_run_violation_count) {
    console.log(
      `There are ${last_run_violation_count} violations in ${project_name}!`
    )
    console.log(`See ${axe_url} for more information`)
  } else {
    console.log('axe clean!')
  }
}

main()

Bash

This example uses curl and jq to return the number of violations on standard output.

#!/bin/bash

if [ -z $API_KEY ] || [ -z $PROJECT_ID ] || [ -z $GIT_SHA ]; then
  echo "Must set the API_KEY, PROJECT_ID, and GIT_SHA environment variables."
  exit 1
fi

curl --fail -H "Accept: application/json" -H "X-API-Key: $API_KEY" "https://axe.deque.com/api-pub/v1/axe-watcher/gh/$GIT_SHA?project_id=$PROJECT_ID" | jq '.last_run_violation_count'

If the web service returns a server error, curl --fail exits with code 22 and suppresses the response body. Use the --fail-with-body option to also return the response JSON as part of standard output.