Obtener Resultados Programáticamente

El servicio REST de de informes descargables te permite descargar un resumen de tus resultados de accesibilidad de 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 - Encuentra una clave API personal correspondiente a tu proyecto o agrega una nueva clave API en el Portal de Cuentas Axe. Elige una clave API de Axe Developer Hub si tu proyecto usa las API web, CLI o Watcher. Usa una clave API de Axe DevTools Mobile para proyectos móviles.
• ID del proyecto - Proporciona el ID del proyecto para los datos del proyecto correspondiente que deseas descargar. Encuentra tu ID de proyecto en Axe Developer Hub.

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

Resumen de la Solicitud

• Punto final: https://axe.deque.com/api-pub/watcher/downloadable/report
• de 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 deseas 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 rama Git especificado.
    • 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 del commit 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 de Solicitud 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>'

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

Objeto source

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

Objeto test_details

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

Objeto commit

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

Objeto devhub_summary

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

Objeto issue_count_by_impact

Desglosa los problemas por nivel de impacto:

Arreglo issue_count_by_rule

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 respuesta 401 Unauthorized.

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 respuesta 404 Not Found.

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 parámetro de consulta commit_sha no existe en los datos de 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 de 404.

Cuerpo de la respuesta

{
  "error": "Session not found"
}

Manejando una Respuesta 202 Processing

Este script de demostración en shell muestra cómo usar curl para volver a solicitar tu informe si recibes una respuesta 202 Processing. Dado que los suites de prueba 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 continuamente reintente y compruebe si los resultados ya están disponibles. Volverá a intentar la solicitud hasta 20 veces, con un retraso de cinco segundos entre intentos.

La muestra requiere que la variable de entorno API_KEY se establezca en tu clave API y PROJECT_ID se establezca en tu 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