Obtenha Resultados Programaticamente

O serviço REST serviço de relatórios para download permite baixar um resumo dos seus resultados de acessibilidade do Axe Developer Hub como dados JSON, para processamento adicional ou importação em outros softwares. O serviço GET possui dois parâmetros obrigatórios:

• Chave de API - Encontre uma chave de API pessoal correspondente ao seu projeto ou adicione uma nova chave de API no Portal de Contas do Axe. Escolha uma chave de API do Axe Developer Hub se seu projeto usar as APIs da web, CLI ou Watcher. Use uma chave de API do Axe DevTools Mobile para projetos móveis.
• ID do Projeto - Forneça o ID do projeto para os dados do projeto correspondentes que você deseja baixar. Encontre seu ID de projeto em Axe Developer Hub.

Você pode usar dois parâmetros opcionais para limitar sua consulta a um branch específico do Git ou a um SHA do commit do Git específico.

Sumário da Solicitação

• Ponto de Extremidade: https://axe.deque.com/api-pub/watcher/downloadable/report
• de Solicitação: GET
• Cabeçalhos (Obrigatórios):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json
• Parâmetros de consulta:
  • project_id (Obrigatório)
    • Descrição: Especifica o ID do projeto para o relatório do projeto que você deseja baixar. Este parâmetro é obrigatório.
    • Exemplo de uso: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>
  • branch_name (Opcional)
    • Descrição: Retorna o relatório disponível para download para o nome do branch especificado do Git.
    • Exemplo de uso: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&branch_name=<GIT_BRANCH>
  • commit_sha (Opcional)
    • Descrição: Retorna o relatório disponível para download para o SHA de commit especificado do Git.
    • Exemplo de uso: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&commit_sha=<GIT_COMMIT_SHA>

Exemplo de solicitação curl

curl -L -H 'Accept: application/json' -H 'X-API-Key: <DEQUE_API_KEY>' 'https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>'

Exemplo de Corpo de Resposta

{
  "report_id": "a4990926-3014-4799-aa39-7aca31fce412",
  "source": {
    "product_name": "axe-devtools-html",
    "product_component_name": "axe-devtools-watcher",
    "product_version": "3.20.2"
  },
  "test_details": {
    "test_id": "da0c79a5-6f1e-4692-a255-5757629208fa",
    "start_date": "2025-05-05T20:02:31.883Z",
    "end_date": "2025-05-05T20:02:42.789Z"
  },
  "commit": {
    "sha": "f73ea5a02386b359ffa79a76473f7a5ad41759d5",
    "author": "John Doe",
    "author_email": "john.doe@example.com",
    "message": "Merge pull request #233 from deque/221-add-examples-for-using-global-config-fields-2",
    "branch_name": "main",
    "repository_url": "https://github.com/dequelabs/watcher-examples.git",
    "tag": null
  },
  "devhub_summary": {
    "issue_count_total": 17,
    "issue_count_by_impact": {
      "critical": 0,
      "serious": 2,
      "moderate": 15,
      "minor": 0
    },
    "issue_count_by_rule": [
      {
        "severity": "serious",
        "rule_id": "color-contrast",
        "rule_help": "Elements must meet minimum color contrast ratio thresholds",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/color-contrast?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "heading-order",
        "rule_help": "Heading levels should only increase by one",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/heading-order?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "landmark-one-main",
        "rule_help": "Document should have one main landmark",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/landmark-one-main?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "page-has-heading-one",
        "rule_help": "Page should contain a level-one heading",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/page-has-heading-one?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "region",
        "rule_help": "All page content should be contained by landmarks",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/region?application=axeAPI",
        "count": 9
      }
    ]
  }
}

Objeto de Resposta

As seções a seguir descrevem os objetos JSON no corpo da resposta.

Estrutura de Nível Superior

Objeto source

Contém informações sobre o produto que gerou o relatório:

Objeto test_details

Contém informações sobre a execução do teste:

Objeto commit

Contém informações sobre o commit do Git associado ao teste:

Objeto devhub_summary

Contém informações resumidas sobre problemas de acessibilidade encontrados:

Objeto issue_count_by_impact

Divide problemas por nível de impacto:

Array issue_count_by_rule

Cada objeto neste array representa uma regra com a seguinte estrutura:

Respostas Adicionais

202 Processing

Esta resposta indica que o relatório ainda está sendo gerado, e você deve tentar novamente sua requisição após esperar.

Corpo da resposta

{
  "message": "Report is still processing",
  "state": "PROCESSING"
}

400 Bad Request

O valor fornecido para commit_sha não é um valor SHA-1.

Corpo da resposta

{
  "error": "commit_sha must be a valid SHA-1 hash"
}

401 Unauthorized

Uma das mensagens de erro a seguir acompanhará a resposta 401 Unauthorized.

A chave de API especificada não é válida

Corpo da resposta

{
  "error": "Invalid API key"
}

Não há um cabeçalho obrigatório com uma chave de API:

Corpo da resposta

{
  "error": "X-API-Key or Authorization header required"
}

404 Not Found

Uma das mensagens de erro a seguir acompanhará a resposta 404 Not Found.

O valor SHA usado com commit_sha não pôde ser localizado

Este erro indica que não há dados para este SHA no Axe Developer Hub, o que normalmente significa que a suíte de testes não foi executada contra este commit do Git. Observe que este é o mesmo erro retornado com um nome de branch que não existe. (Veja o próximo erro.)

Corpo da resposta

{
  "error": "Session not found"
}

O valor fornecido para branch_name não existe

Esta resposta de erro é a mesma que o erro anterior (se o SHA fornecido com o parâmetro de consulta commit_sha não existir nos dados do Axe Developer Hub).

Corpo da resposta

{
  "error": "Session not found"
}

O valor fornecido para project_id não existe

Esta resposta de erro é igual aos erros anteriores 404.

Corpo da resposta

{
  "error": "Session not found"
}

Tratando uma resposta 202 Processing

Este script de demonstração em shell mostra como usar curl para solicitar novamente seu relatório caso você receba uma resposta 202 Processing. Como as suítes de teste podem encontrar inúmeras violações de acessibilidade, nosso sistema pode requerer tempo adicional para processar todos os resultados antes que o relatório esteja pronto para download. Recomendamos usar o exemplo abaixo para criar um script que tentará continuamente até que os resultados estejam disponíveis. Ele tentará a solicitação até 20 vezes, com um atraso de cinco segundos entre as tentativas.

O exemplo exige que a variável de ambiente API_KEY seja definida com sua chave de API e PROJECT_ID seja definida com seu ID de projeto.

#!/bin/bash

URL="https://axe.deque.com/api-pub/watcher/downloadable/report"
MAX_ATTEMPTS=20
DELAY=5
TEMP_FILE=$(mktemp)

for ((i=1; i<=MAX_ATTEMPTS; i++)); do
    echo "Attempt $i..."
    
    # Get both status and response
    STATUS=$(curl -s -w '%{http_code}' -L -H "Accept: application/json" -H "X-API-Key: $API_KEY" -o "$TEMP_FILE" "$URL?project_id=$PROJECT_ID")
    
    case $STATUS in
        200)
            echo "Success!"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE"
            exit 0
            ;;
        202)
            echo "Still processing, waiting ${DELAY}s..."
            sleep $DELAY
            ;;
        *)
            echo "Error: HTTP $STATUS"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE"
            exit 1
            ;;
    esac
done

echo "Timeout after $MAX_ATTEMPTS attempts"
rm "$TEMP_FILE"
exit 1