Obtener Resultados Programáticamente

Migrar a la API de Sesiones y Resultados

El nuevo API de Sesiones y Resultados reemplaza este punto de acceso con dos puntos de acceso separados: uno para listar sesiones de un proyecto y otro para recuperar resultados de una sesión específica. Este modelo de dos pasos le da acceso a todas las sesiones a través de ramas y commits, no solo a la más reciente.

Solicitud equivalente usando format=summary

El modo format=summary del punto de acceso de Resultados devuelve la misma estructura JSON que este punto de acceso. Para replicar una solicitud existente, primero encuentre la sesión que coincide con su rama o commit, luego solicite sus resultados:

1. Listar sesiones para encontrar la session_id para la rama o commit que le interese, usando los filtros git_branch o commit_sha:

   curl -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
     "https://axe.deque.com/api-pub/v1/results/projects/$PROJECT_ID/sessions?git_branch=$GIT_BRANCH"

2. Solicitar resultados para esa sesión por session_id, usando format=summary para la misma estructura JSON que este punto de acceso:

   curl -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
     "https://axe.deque.com/api-pub/v1/results/sessions/$SESSION_ID/results?format=summary"

   important

   El nuevo punto de acceso devuelve 204 No Content mientras se generan los resultados, no 202 Processing como hace este punto de acceso. Si tiene código existente que verifica una respuesta 202, actualícelo para manejar 204 en su lugar. Consulte Estado de la Sesión y el Patrón de Sondeo para un ejemplo completo de sondeo.

Profundizando con format=full

Si desea el detalle completo a nivel de problema más allá de lo que proporciona el resumen, use format=full para recuperar resultados en JSON Universal (Formato Común de Exportación). Este formato incluye cada problema de accesibilidad encontrado durante la sesión: violaciones individuales, verificaciones incompletas, aprobaciones y reglas inaplicables organizadas por página.

curl -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
  "https://axe.deque.com/api-pub/v1/results/sessions/$SESSION_ID/results?format=full"

Referencia del Punto de Acceso Heredado

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

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

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

Resumen de la Solicitud

• Punto de acceso: https://axe.deque.com/api-pub/watcher/downloadable/report
• Solicitud: GET
• Encabezados (Obligatorios):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json
• Parámetros de consulta:
  • project_id (Requerido)
    • 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 rama de 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 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 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

sourceObjeto

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

test_detailsObjeto

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

commitObjeto

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

devhub_summaryObjeto

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

issue_count_by_impactObjeto

Desglosa problemas por nivel de impacto:

issue_count_by_ruleMatriz

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

Respuestas adicionales

202 Processing

Esta respuesta indica que el informe todavía se está generando y necesita volver a intentar su solicitud después de esperar.

Cuerpo de la respuesta

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

429 Too Many Requests

Durante períodos de alta carga, este endpoint puede responder con 429 Too Many Requests en lugar de iniciar el procesamiento de inmediato. El trabajo subyacente permanece en cola, por lo que volver a intentarlo no crea un procesamiento duplicado. La respuesta incluye un encabezado Retry-After, en segundos; espere al menos ese tiempo antes de intentar nuevamente.

Cuerpo de la respuesta

{
  "error": "Too many requests. Retry after the Retry-After interval."
}

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

La clave de API especificada no es válida

Cuerpo de la respuesta

{
  "error": "Invalid API key"
}

No hay un encabezado requerido con una clave de 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á a la respuesta 404 Not Found.

No se pudo encontrar el valor SHA utilizado con commit_sha

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_nameno 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 del Axe Developer Hub).

Cuerpo de la respuesta

{
  "error": "Session not found"
}

El valor suministrado para project_idno existe

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

Cuerpo de la respuesta

{
  "error": "Session not found"
}

Manejo de una respuesta 202 Processing

Este script de demostración muestra cómo usar curl para solicitar nuevamente su informe si recibe una respuesta 202 Processing. Dado que las 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 continúe intentándolo para ver si los resultados ya están disponibles. Volverá a intentar la solicitud hasta 20 veces, con un retraso de cinco segundos entre intentos.

El ejemplo requiere que la variable de entorno API_KEY se establezca en su clave de API y PROJECT_ID se establezca en 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