Obter 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 adicional ou importação em outros softwares. O serviço GET tem dois parâmetros obrigatórios:

• **Chave API** - Encontre uma chave API pessoal correspondente ao seu projeto ou adicione uma nova chave API no Portal de Conta Axe. Escolha uma chave API do Axe Developer Hub se seu projeto usa as APIs web, CLI ou Watcher. Use uma chave 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 de projeto em Axe Developer Hub.

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

Resumo da Solicitação

• **Endpoint**: https://axe.deque.com/api-pub/watcher/downloadable/report
• **Requisição**: GET
• **Cabeçalhos (Obrigatório)**:
  • 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 de ramo 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 Git commit SHA 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 Requisiçã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 Git associado ao teste:

devhub_summary Objeto

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

issue_count_by_impact Objeto

Divide 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ê precisa tentar novamente após aguardar.

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 da API especificada não é válida

Corpo da resposta

{
  "error": "Invalid API key"
}

Não há cabeçalho necessário com uma chave 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 geralmente significa que a suíte de testes não foi executada contra este commit Git. Note que este é o mesmo erro retornado com um nome de ramificação 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 do erro anterior (se o SHA fornecido com o commit_sha parâmetro de consulta 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 dos 404 erros anteriores.

Corpo da resposta

{
  "error": "Session not found"
}

Lidando com uma 202 Processing Resposta

Este script shell de demonstração mostra como usar curl para solicitar novamente o seu relatório se você receber uma 202 Processing resposta. Como as suítes de teste podem encontrar inúmeras violações de acessibilidade, nosso sistema pode exigir 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 continuará tentando ver se os resultados já estão disponíveis. Ele tentará novamente a solicitaçã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 definida para sua chave de API e PROJECT_ID seja definida para o ID do seu 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