Obtenha Resultados Programaticamente

O serviço de relatórios para download REST permite que você baixe um resumo dos seus resultados de acessibilidade do Axe Developer Hub como dados JSON, para processamento posterior ou importação para outros softwares. O serviço GET requer 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 o seu projeto usar as APIs 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 correspondente que você deseja baixar. Encontre seu ID do projeto no Axe Developer Hub.

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

Sumário da Solicitação

• Ponto de Extremidade: https://axe.deque.com/api-pub/watcher/downloadable/report
• Requisiçã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 para download para o nome do branch Git especificado.
    • 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 para download para o SHA do commit Git especificado.
    • Exemplo de uso: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&commit_sha=<GIT_COMMIT_SHA>

Exemplo curl de Solicitação

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

source Objeto

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

test_details Objeto

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

commit Objeto

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

devhub_summary Object

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

issue_count_by_impact Object

Detalha os problemas por nível de impacto:

issue_count_by_rule Array

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 seguintes mensagens de erro acompanhará a 401 Unauthorized resposta.

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 seguintes mensagens de erro acompanhará a 404 Not Found resposta.

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 no 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 é a mesma que os anteriores 404 erros.

Corpo da resposta

{
  "error": "Session not found"
}

Lidando com uma 202 Processing Resposta

Este script de demonstração em shell mostra como usar curl para re-solicitar seu relatório se você receber uma 202 Processing resposta. Como as suítes de teste podem encontrar diversas 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 irá tentar continuamente e verificar se os resultados já estão disponíveis. Ele tentará novamente a requisição até 20 vezes, com um atraso de cinco segundos entre as tentativas.

O exemplo requer que a variável de ambiente API_KEY seja configurada para a sua chave de API e PROJECT_ID para que seja configurada para a sua 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