API-Referenz für Sitzungen und Ergebnisse

Die API für Sitzungen und Ergebnisse gibt Ihnen programmatischen Zugriff auf Ihre Axe Developer Hub-Sitzungen und deren Barrierefreiheitsergebnisse. Verwenden Sie den Sitzungen-Endpunkt, um Sitzungen für ein Projekt zu entdecken, und nutzen Sie dann den Ergebnisse-Endpunkt, um die detaillierten Ergebnisse einer bestimmten Sitzung abzurufen.

Beide Endpunkte erfordern eine Projekt-ID. Finden Sie sie im Axe Developer Hub oder recherchieren Sie sie nach Projektname mit der Projects API.

Authentifizierung

Alle Anfragen erfordern einen API-Schlüssel. Stellen Sie ihn mit dem X-API-Key Header bereit:

X-API-Key: <DEQUE_API_KEY>

Finden Sie Ihren API-Schlüssel im Axe Account Portal. Wählen Sie einen Axe Developer Hub API-Schlüssel für Web- oder CI/CD-Projekte oder einen Axe DevTools Mobile API-Schlüssel für mobile Projekte.

Behandeln Sie Ihren API-Schlüssel als Geheimnis: Speichern Sie ihn in einer Umgebungsvariablen oder im Geheimnisspeicher Ihrer CI/CD-Plattform, anstatt ihn fest in Ihre Anfragen zu kodieren.

Zugangskontrolle

Die folgenden Zugriffsregeln gelten für beide Endpunkte:

• Projektmitglieder können auf Sitzungen und Ergebnisse für jedes Projekt zugreifen, dem sie angehören.
• Organisationsadministratoren mit einem aktiven Axe Developer Hub- oder Axe DevTools Mobile-Abonnement können auf Sitzungen und Ergebnisse für jedes Projekt in ihrer Organisation zugreifen, unabhängig von der Projektmitgliedschaft. Der Zugriff ist auf das Produkt des API-Schlüssels beschränkt: Ein API-Schlüssel vom Axe Developer Hub liefert nur Daten des Axe Developer Hubs, und ein API-Schlüssel von Axe DevTools Mobile liefert nur Daten von Axe DevTools Mobile. Ein Organisationsadministrator kann keinen Axe DevTools Mobile API-Schlüssel verwenden, um Axe Developer Hub-Daten abzurufen, oder umgekehrt.
• Nicht-Mitglieder, Nicht-Administratoren erhalten eine Antwort mit Zugriffsverweigerung.
• Ein inaktives Abonnement liefert 401 Unauthorized.

Sitzungen-Endpunkt

Gibt eine paginierte, filterbare Liste von Sitzungen für ein bestimmtes Projekt zurück.

Anfrage

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

Ersetzen Sie {project_id} durch die ID des Projekts, dessen Sitzungen Sie abrufen möchten. Finden Sie Ihre Projekt-ID in Axe Developer Hub.

Abfrageparameter

Alle Abfrageparameter sind optional.

Antwortkörper

Eine erfolgreiche Antwort gibt ein JSON-Objekt mit einem sessions-Array zurück. Jedes Sitzungsobjekt enthält die folgenden Felder:

Beispielantwortkörper

{
  "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"
    }
  ]
}

Cursor-Paginierung

Der Sessions-Endpunkt verwendet eine cursor-basierte Paginierung. Wenn es mehr Ergebnisse gibt als auf der aktuellen Seite angezeigt werden, wird ein intransparenter Cursorwert im x-pagination-cursor-Antwortheader zurückgegeben. Übergeben Sie diesen Wert als after-Abfrageparameter in Ihrer nächsten Anfrage, um die nächste Seite abzurufen.

Wenn der x-pagination-cursor-Header nicht in der Antwort enthalten ist, haben Sie die letzte Seite erreicht.

E-Mail-Filterbegrenzung

Fehlerantworten des Sessions-Endpunkts

Ergebnisse-Endpunkt

Gibt die Barrierefreiheitsergebnisse für eine bestimmte Sitzung zurück. Die Ergebnisse werden asynchron zurückgegeben: Wenn die Ergebnisse noch nicht bereit sind, gibt der Endpunkt 204 No Content zurück und Sie müssen warten, bis sie bereit sind.

Deduplizierung

Bei Webprojekten geben beide Antwortformate deduplizierte Ergebnisse zurück. Wenn dasselbe Problem in mehr als einem Seitenzustand der Sitzung gefunden wird, wird es einmal unter dem ersten Seitenzustand gemeldet, in dem es gefunden wurde. Zwei Ergebnisse zählen als dasselbe Problem, wenn sie dieselbe Regel und dieselbe Seiten-URL sowie dasselbe Element haben, übereinstimmend durch CSS-Selektor, XPath oder Vorfahren. Siehe Duplikat für die vollständigen Übereinstimmungsregeln.

• format=summary: Die Problemzählungen nach Auswirkung und Regel zählen jedes eindeutige Problem einmal.
• format=full: Jedes eindeutige Problem erscheint einmal in der Problemliste, und die Summen im Header sind eindeutige Zählungen.

Die Deduplizierung erfolgt nur innerhalb einer einzelnen Sitzung: Ergebnisse werden nicht mit anderen Sitzungen verglichen, und die Antwort gibt nicht an, wie viele Duplikate entfernt wurden oder ob ein Problem neu ist. Mobile Ergebnisse werden nicht dedupliziert.

Anfrage

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

Ersetzen Sie {session_id} durch den von dem Sessions-Endpunkt zurückgegebenen session_id-Wert. Es muss eine gültige UUID sein.

Abfrageparameter

Sitzungsstatus und das Polling-Muster

Wenn die Ergebnisse einer Sitzung noch nicht verarbeitet wurden, löst der Ergebnisse-Endpunkt die Verarbeitung automatisch aus und antwortet mit 204 No Content (kein Antwortkörper). Ihr Client muss den gleichen Endpunkt abfragen, bis eine 200 OK-Antwort erhalten wird.

Umgang mit 429 Too Many Requests

Während Zeiten hoher Auslastung kann der Ergebnisse-Endpunkt mit 429 Too Many Requests antworten, anstatt die Verarbeitung sofort auszulösen. Dies bedeutet nicht, dass Ihre Anfrage verloren ging: Die zugrunde liegende Arbeit bleibt in der Warteschlange, und ein erneuter Versuch führt nicht zu einer doppelten Verarbeitung für die gleiche Sitzung.

Eine 429-Antwort enthält einen Retry-After-Header in Sekunden. Warten Sie mindestens so lange, bevor Sie es erneut versuchen — das untenstehende Beispiel behandelt dies zusammen mit dem normalen 204-Polling-Fall.

Antwortkörper

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

Beispiel: Polling für Ergebnisse

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

Antwortformate

format=summary(Standard)

Gibt dieselbe JSON-Struktur wie die legacy downloadable-report endpoint zurück. Verwenden Sie dieses Format, wenn Sie bereits vorhandene Tools haben, die gegen den downloadable-report endpoint entwickelt wurden und Sie einen Ersatz benötigen.

format=full

Gibt die vollständigen ergebnisbezogenen Ergebnisse in Universelles JSON (gemeinsames Exportformat) zurück. Dieses Format enthält jedes während der Sitzung gefundene Barrierefreiheitsproblem, einschließlich Detailinformationen auf Seiten- und Regel-Ebene.

Die Antwort wird mit Content-Encoding ausgeliefert, das aus dem Accept-Encoding-Header des Clients ausgehandelt wurde.

Fehlerantworten des Ergebnisse-Endpunkts

Häufige Arbeitsabläufe

Alle Sitzungen für ein Projekt abrufen und vollständige Ergebnisse herunterladen

Dieses Beispiel verwendet curl und jq, um alle Sitzungen für ein Projekt durchzublättern und die vollständigen Universal-JSON-Ergebnisse für jede herunterzuladen. Bei Webprojekten enthält jede Datei die deduplizierten Probleme der Sitzung; siehe Deduplizierung.

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