Erste Schritte mit den APIs des Axe Developer Hub

Jede API des Axe Developer Hub verwendet dasselbe Setup: einen Axe Account API-Schlüssel, der in einem Anfrage-Header gesendet wird, und für die meisten Anfragen eine Projekt-ID. Dieser Leitfaden führt Sie einmal durch dieses Setup, macht einen ersten Aufruf, um zu bestätigen, dass es funktioniert, und zeigt Ihnen dann die API für die Aufgabe, die Sie im Sinn haben.

Holen Sie sich Ihren API-Schlüssel

1. Melden Sie sich im Axe Account-Portal an.
2. Kopieren Sie einen API-Schlüssel für das Produkt, das Ihr Projekt verwendet:
   • Ein API-Schlüssel des Axe Developer Hub für Web- und CI/CD-Projekte.
   • Ein API-Schlüssel für Axe DevTools Mobile für mobile Projekte.

Ein API-Schlüssel liefert nur Daten für sein eigenes Produkt. Ein API-Schlüssel des Axe Developer Hub kann keine Daten von Axe DevTools Mobile abrufen, und ein API-Schlüssel für Axe DevTools Mobile kann keine Daten des Axe Developer Hub abrufen, selbst für einen Organisationsadministrator. Welche Projekte ein Schlüssel innerhalb seines Produkts zugreifen kann, hängt von Ihrer Projektmitgliedschaft und Rolle ab: siehe Zugangskontrolle in der Sessions- und Ergebnis-API-Referenz und der Projekte-API-Referenz.

Senden Sie den API-Schlüssel mit jeder Anfrage

Senden Sie Ihren API-Schlüssel im X-API-Key-Header jeder Anfrage und fordern Sie eine JSON-Antwort mit dem Accept-Header an:

X-API-Key: <DEQUE_API_KEY>
Accept: application/json

Behandeln Sie Ihren API-Schlüssel als Geheimnis: Speichern Sie ihn in einer Umgebungsvariablen oder im Geheimnis-Speicher Ihrer CI/CD-Plattform, anstatt ihn in Ihre Anfragen zu festzucodieren. Die Beispiele in diesem Leitfaden lesen ihn aus einer API_KEY Umgebungsvariablen.

Finden Sie Ihre Projekt-ID

Die meisten Anfragen identifizieren ein Projekt anhand seiner Projekt-ID. Sie können diese auf zwei Arten finden:

• Im Axe Developer Hub: Gehen Sie zu Ihrem Projekte, öffnen Sie das Einstellungen-Menü für Ihr Projekt und wählen Sie Projekt konfigurieren. Die Projekt-ID erscheint oben auf der Anleitungsseite.
• Mit der Projekte-API: Suchen Sie die ID anhand des Projektnamens. Siehe Eine Projekt-ID nach Name suchen.

Tätigen Sie Ihren ersten Anruf

Listen Sie die Projekte auf, auf die Ihr API-Schlüssel zugreifen kann. Diese Anfrage benötigt keine Projekt-ID, daher ist es ein schneller Weg, um zu bestätigen, dass Ihr Schlüssel funktioniert:

curl -s \
  -H "Accept: application/json" \
  -H "X-API-Key: $API_KEY" \
  "https://axe.deque.com/api-pub/v1/results/projects"

Eine 200 OK-Antwort mit einem JSON-Array von Projekten bedeutet, dass Ihr Schlüssel gültig und aktiv ist. Die project_id jedes Projekts ist die ID, die Sie in den anderen APIs verwenden sollen. Wenn Sie stattdessen 401 Unauthorized erhalten, überprüfen Sie, ob Sie den gesamten Schlüssel kopiert haben und ob er zu dem Produkt gehört, das Ihre Projekte verwenden.

Wählen Sie Ihre Aufgabe

Eine CI/CD-Pipeline blockieren

Verwenden Sie die Commit-Status-API, um einen Pull-Request oder ein Commit zu blockieren, wenn Barrierefreiheitsfehler gefunden werden. Ihre Anfrage gibt einen Git-Commit-SHA und eine Projekt-ID weiter, und die Antwort meldet die Anzahl der Barrierefreiheitsfehler aus dem Testlauf dieses Commits und wie viele über Ihrem a11y-Schwellenwert liegen. Ihr Projekt muss Git-Daten verwenden.

Wenn Ihre Pipeline auf GitHub läuft, die GitHub-Action verwenden anstatt die API direkt aufzurufen.

Barrierefreiheitsergebnisse abrufen

Verwenden Sie die Sitzungen- und Ergebnis-API, um Ergebnisse herunterzuladen. Rufen Sie den Sitzungsendpunkt auf, um die Sitzungen eines Projekts aufzulisten, und übergeben Sie dann die session_id einer Sitzung an den Ergebnisendpunkt.

Zwei Verhaltensweisen des Ergebnisendpunkts beeinflussen, wie Sie Ihren Client schreiben:

• Ergebnisse können Zeit zur Vorbereitung benötigen. Eine 204 No Content-Antwort bedeutet, dass die Ergebnisse noch nicht bereit sind. Warten Sie kurz und wiederholen Sie die Anfrage, bis Sie 200 OK erhalten. Siehe Sitzungsstatus und Polling-Muster.
• Ergebnisse werden am schnellsten mit Brotli-Kompression heruntergeladen. Senden Sie Accept-Encoding: br (oder verwenden Sie curl --compressed mit einem Brotli-fähigen curl), insbesondere für format=full. Siehe Antwortkompression.

Projekte und Mitglieder verwalten

Verwenden Sie Projekte-API, um Ihre Projekte aufzulisten, durch sie zu blättern oder eine Projekt-ID nach Namen zu finden. Sie können auch Projekte erstellen, aktualisieren und löschen sowie Projektmitglieder hinzufügen, ändern oder entfernen. Um diese Arbeit zu automatisieren, beginnen Sie mit Erste Schritte mit der Projektmanagement-Automatisierung.

Fehler und Wiederholungsversuche behandeln

Die APIs des Axe Developer Hub teilen einen gemeinsamen Satz von Fehlerantworten:

Wenn Sie den Ergebnisse-Endpunkt abfragen, ist 204 No Content kein Fehler: Es bedeutet, dass die Ergebnisse noch nicht bereit sind, und Sie denselben Antrag nach kurzer Wartezeit wiederholen. Warten Sie länger zwischen den Wiederholungen, je öfter Sie wiederholen, und geben Sie nach einem vernünftigen Limit auf, damit eine blockierte Sitzung Ihre Pipeline nicht unbegrenzt aufhält.

Jede Referenzseite listet die genauen Fehlerantworten für ihre Endpunkte auf. Bauen Sie Ihre Wiederholungslogik so auf, dass sie 429 Too Many Requests von jedem Endpunkt behandeln kann, nicht nur vom Ergebnisse-Endpunkt.