Riferimento API Sessioni e Risultati

L'API Sessioni e Risultati ti offre l'accesso programmato alle tue sessioni dell'Axe Developer Hub e ai loro risultati di accessibilità. Usa l'Endpoint delle Sessioni per scoprire le sessioni di un progetto, quindi usa l'Endpoint dei Risultati per recuperare i risultati dettagliati di una sessione specifica.

Entrambi gli endpoint richiedono un ID di progetto. Trovalo in Axe Developer Hub oppure cercalo per nome del progetto con la API Progetti.

Autenticazione

Tutte le richieste richiedono una chiave API. Forniscila utilizzando l'header X-API-Key:

X-API-Key: <DEQUE_API_KEY>

Trova la tua chiave API nel Portale Account Axe. Scegli una chiave API Axe Developer Hub per progetti web o CI/CD, oppure una chiave API Axe DevTools Mobile per progetti mobili.

Controllo dell'accesso

Le seguenti regole di accesso si applicano ad entrambi gli endpoint:

• Membri del progetto possono accedere alle sessioni e ai risultati di qualsiasi progetto a cui appartengono.
• Amministratori dell'organizzazione con un abbonamento attivo a Axe Developer Hub o Axe DevTools Mobile possono accedere alle sessioni e ai risultati di qualsiasi progetto nella loro organizzazione, indipendentemente dall'appartenenza al progetto. L'accesso è limitato al prodotto della chiave API: una chiave API Axe Developer Hub restituisce solo dati Axe Developer Hub e una chiave API Axe DevTools Mobile restituisce solo dati Axe DevTools Mobile. Un amministratore dell'organizzazione non può utilizzare una chiave API Axe DevTools Mobile per recuperare dati Axe Developer Hub, né una chiave API Axe Developer Hub per recuperare dati Axe DevTools Mobile.
• Utenti non membri, non amministratori ricevono una risposta di accesso negato.
• Un abbonamento inattivo restituisce 401 Unauthorized.

Endpoint delle Sessioni

Restituisce un elenco di sessioni paginato e filtrabile per un determinato progetto.

Richiesta

• Endpoint: GET https://axe.deque.com/api-pub/v1/results/projects/{project_id}/sessions
• Intestazioni (richieste):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json

Sostituisci {project_id} con l'ID del progetto di cui vuoi recuperare le sessioni. Trova il tuo ID di progetto in Axe Developer Hub.

Parametri di Query

Tutti i parametri di query sono opzionali.

Corpo della Risposta

Una risposta di successo restituisce un oggetto JSON con un array sessions. Ogni oggetto sessione contiene i seguenti campi:

Esempio di corpo della risposta

{
  "sessions": [
    {
      "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Main CI run for PR 451",
      "created_at": "2026-06-01T14:23:00.000Z",
      "is_canonical_source": true,
      "git_branch": "feature/new-nav",
      "git_url": "https://github.com/example/webapp",
      "commit_sha": "9eabf5b536662000f79978c4d1b6e4eff5c8d785",
      "created_by_user_name": "Jane Smith",
      "created_by_user_email": "jane.smith@example.com",
      "created_by_user_api_key_name": "CI Pipeline Key"
    },
    {
      "session_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
      "created_at": "2026-05-30T09:00:00.000Z",
      "is_canonical_source": false,
      "git_branch": null,
      "git_url": null,
      "commit_sha": null,
      "created_by_user_api_key_name": "Unknown Member"
    }
  ]
}

Paginazione con Cursore

L'endpoint delle sessioni utilizza la paginazione basata su cursore. Quando ci sono più risultati oltre alla pagina corrente, viene restituito un valore cursore opaco nell'intestazione della risposta x-pagination-cursor. Passa questo valore come parametro di query after nella tua prossima richiesta per recuperare la pagina successiva.

Quando l'intestazione x-pagination-cursor è assente dalla risposta, hai raggiunto l'ultima pagina.

Limitazione Filtro Email

Risposte di errore dell'endpoint delle sessioni

Endpoint dei risultati

Restituisce i risultati di accessibilità per una sessione specifica. I risultati vengono restituiti in modo asincrono: se i risultati non sono ancora pronti, l'endpoint restituisce 204 No Content e si effettua un polling fino a quando non lo sono.

Richiesta

• Endpoint: GET https://axe.deque.com/api-pub/v1/results/sessions/{session_id}/results
• Intestazioni (richieste):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json

Sostituisci {session_id} con il valore session_id restituito dall'endpoint delle sessioni. Deve essere un UUID valido.

Parametri di Query

Stato della sessione e il modello di polling

Quando i risultati di una sessione non sono ancora stati elaborati, l'endpoint dei risultati attiva l'elaborazione automaticamente e risponde con 204 No Content (nessun corpo della risposta). Il tuo client deve effettuare il polling dello stesso endpoint fino a ricevere una risposta 200 OK.

Gestione di 429 Too Many Requests

Durante periodi di carico intenso, l'endpoint dei risultati potrebbe rispondere con 429 Too Many Requests invece di avviare immediatamente l'elaborazione. Questo non significa che la tua richiesta sia andata persa: il lavoro sottostante rimane in coda e riprovare non crea un'elaborazione duplicata per la stessa sessione.

Una risposta 429 include un'intestazione Retry-After, in secondi. Attendi almeno tanto tempo prima di riprovare — l'esempio sotto gestisce questo insieme al normale caso di polling 204.

Corpo della risposta

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

Esempio: Polling per i risultati

#!/bin/bash

SESSION_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
URL="https://axe.deque.com/api-pub/v1/results/sessions/$SESSION_ID/results"
MAX_ATTEMPTS=20
DELAY=5
TEMP_FILE=$(mktemp)

for ((i=1; i<=MAX_ATTEMPTS; i++)); do
    echo "Attempt $i..."

    HEADERS_FILE=$(mktemp)
    STATUS=$(curl -s -w '%{http_code}' -L \
      -H "Accept: application/json" \
      -H "X-API-Key: $API_KEY" \
      -D "$HEADERS_FILE" \
      -o "$TEMP_FILE" \
      "$URL?format=full")

    case $STATUS in
        200)
            echo "Results ready!"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE" "$HEADERS_FILE"
            exit 0
            ;;
        204)
            echo "Still processing, waiting ${DELAY}s..."
            sleep $DELAY
            ;;
        429)
            RETRY_AFTER=$(grep -i '^retry-after:' "$HEADERS_FILE" | tr -d '\r' | awk '{print $2}')
            RETRY_AFTER=${RETRY_AFTER:-$DELAY}
            echo "Too many requests, waiting ${RETRY_AFTER}s per Retry-After..."
            sleep "$RETRY_AFTER"
            ;;
        *)
            echo "Error: HTTP $STATUS"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE" "$HEADERS_FILE"
            exit 1
            ;;
    esac
    rm -f "$HEADERS_FILE"
done

echo "Timeout after $MAX_ATTEMPTS attempts"
rm "$TEMP_FILE"
exit 1

Formati di risposta

format=summary (predefinito)

Restituisce la stessa struttura JSON di endpoint legacy per il rapporto scaricabile. Usa questo formato se hai strumenti esistenti costruiti per l'endpoint del rapporto scaricabile e desideri un rimpiazzo facile.

format=full

Restituisce i risultati completi a livello di problema in JSON universale (Formato di Esportazione Comune). Questo formato include ogni problema di accessibilità trovato durante la sessione, inclusi dettagli a livello di pagina e regola.

La risposta viene fornita con Content-Encoding negoziato dall'intestazione Accept-Encoding del client.

Risposte di errore dell'endpoint dei risultati

Flussi di lavoro comuni

Recupera tutte le sessioni per un progetto e scarica i risultati completi

Questo esempio utilizza curl e jq per scorrere tutte le sessioni di un progetto e scaricare i risultati completi in formato JSON universale per ciascuna.

#!/bin/bash

# Set these environment variables before running:
# API_KEY: your Axe Developer Hub API key
# PROJECT_ID: your project ID

BASE_URL="https://axe.deque.com/api-pub/v1/results"
CURSOR=""

while true; do
    QUERY="page_size=100"
    if [ -n "$CURSOR" ]; then
        QUERY="$QUERY&after=$CURSOR"
    fi

    RESPONSE=$(curl -s -D - -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
      "$BASE_URL/projects/$PROJECT_ID/sessions?$QUERY")

    NEXT_CURSOR=$(echo "$RESPONSE" | grep -i "x-pagination-cursor:" | tr -d '\r' | awk '{print $2}')
    BODY=$(echo "$RESPONSE" | sed -n '/^\r\{0,1\}$/,$p' | tail -n +2)

    SESSION_IDS=$(echo "$BODY" | jq -r '.sessions[].session_id')

    for SESSION_ID in $SESSION_IDS; do
        echo "Fetching results for session $SESSION_ID..."

        while true; do
            STATUS=$(curl -s -w '%{http_code}' -L \
              -H "Accept: application/json" \
              -H "X-API-Key: $API_KEY" \
              -o "${SESSION_ID}.json" \
              "$BASE_URL/sessions/$SESSION_ID/results?format=full")

            if [ "$STATUS" = "200" ]; then
                echo "Saved ${SESSION_ID}.json"
                break
            elif [ "$STATUS" = "204" ]; then
                echo "  Still processing, waiting..."
                sleep 5
            else
                echo "  Error: HTTP $STATUS"
                break
            fi
        done
    done

    if [ -z "$NEXT_CURSOR" ]; then
        break
    fi
    CURSOR="$NEXT_CURSOR"
done