Obtener Resultados Programáticamente

El servicio de informes descargables REST le permite descargar un resumen de sus resultados de accesibilidad del Axe Developer Hub como datos JSON, para su posterior procesamiento o importación en otro software. El servicio GET tiene dos parámetros obligatorios:

• Clave API - Encuentre una clave API personal correspondiente a su proyecto o añada una nueva clave API en el Portal de Cuentas Axe. Elija una clave API del Axe Developer Hub si su proyecto utiliza las API web, CLI o Watcher. Use una clave API de Axe DevTools Mobile para proyectos móviles.
• ID del proyecto - Proporcione el ID del proyecto para los datos del proyecto correspondiente que desea descargar. Encuentre su ID de proyecto en el Axe Developer Hub.

Puede usar dos parámetros opcionales para limitar su consulta a una rama específica de Git o a un SHA de commit de Gitespecífico.

Resumen de la Solicitud

• Punto final: https://axe.deque.com/api-pub/watcher/downloadable/report
• Solicitud: GET
• Encabezados (Obligatorio):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json
• Parámetros de consulta:
  • project_id (Obligatorio)
    • Descripción: Especifica el ID del proyecto para el informe del proyecto que desea descargar. Este parámetro es obligatorio.
    • Uso de ejemplo: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>
  • branch_name (Opcional)
    • Descripción: Devuelve el informe descargable para el nombre de la rama Git especificada.
    • Uso de ejemplo: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&branch_name=<GIT_BRANCH>
  • commit_sha (Opcional)
    • Descripción: Devuelve el informe descargable para el SHA de commit de Git especificado.
    • Uso de ejemplo: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&commit_sha=<GIT_COMMIT_SHA>

Ejemplo curl de Solicitud

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>'

Ejemplo de Cuerpo de Respuesta

{
  "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 Respuesta

Las siguientes secciones describen los objetos JSON en el cuerpo de la respuesta.

Estructura de Nivel Superior

source Objeto

Contiene información sobre el producto que generó el informe:

test_details Objeto

Contiene información sobre la ejecución de la prueba:

commit Objeto

Contiene información sobre el commit de Git asociado con la prueba:

devhub_summary Objeto

Contiene información resumida sobre los problemas de accesibilidad encontrados:

issue_count_by_impact Objeto

Desglosa los problemas por nivel de impacto:

issue_count_by_rule Matriz

Cada objeto de esta matriz representa una regla con la siguiente estructura:

Respuestas Adicionales

202 Processing

Esta respuesta indica que el informe aún se está generando y debe volver a intentar su solicitud después de esperar.

Cuerpo de la respuesta

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

400 Bad Request

El valor proporcionado para commit_sha no es un valor SHA-1.

Cuerpo de la respuesta

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

401 Unauthorized

Uno de los siguientes mensajes de error acompañará la 401 Unauthorized respuesta.

La clave API especificada no es válida

Cuerpo de la respuesta

{
  "error": "Invalid API key"
}

No hay un encabezado requerido con una clave API:

Cuerpo de la respuesta

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

404 Not Found

Uno de los siguientes mensajes de error acompañará la 404 Not Found respuesta.

El valor SHA utilizado con commit_sha no se pudo localizar

Este error indica que no hay datos para este SHA en los datos del Axe Developer Hub, lo que generalmente significa que la suite de pruebas no se ejecutó contra este commit de Git. Tenga en cuenta que este es el mismo error que se devuelve con un nombre de rama que no existe. (Vea el siguiente error.)

Cuerpo de la respuesta

{
  "error": "Session not found"
}

El valor proporcionado para branch_name no existe

Esta respuesta de error es la misma que el error anterior (si el SHA proporcionado con el commit_sha parámetro de consulta no existe en los datos del Axe Developer Hub).

Cuerpo de la respuesta

{
  "error": "Session not found"
}

El valor proporcionado para project_id no existe

Esta respuesta de error es la misma que los errores anteriores. 404

Cuerpo de la respuesta

{
  "error": "Session not found"
}

Manejo de una 202 Processing Respuesta

Este script de demostración en shell muestra cómo usar curl para volver a solicitar su informe si recibe una 202 Processing respuesta. Dado que las suites de pruebas pueden encontrar numerosas violaciones de accesibilidad, nuestro sistema puede requerir tiempo adicional para procesar todos los resultados antes de que el informe esté listo para descargar. Recomendamos usar el ejemplo a continuación para crear un script que vuelva a intentar continuamente y vea si los resultados ya están disponibles. Intentará la solicitud hasta 20 veces, con un retraso de cinco segundos entre intentos.

El ejemplo requiere que el API_KEY variable de entorno esté configurada con su clave API y PROJECT_ID esté configurada con su ID de proyecto.

#!/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