Aan de slag met de Axe Developer Hub-API's

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

Stel authenticatie in, vind uw project-ID en maak uw eerste oproep naar de Axe Developer Hub REST-API's

Not for use with personal data

Elke Axe Developer Hub-API gebruikt dezelfde set-up: een Axe-account-API-sleutel die in een aanvraagheader wordt verzonden, en voor de meeste aanvragen een project-ID. In deze handleiding wordt die set-up eenmalig doorlopen, wordt er een eerste oproep gedaan om te bevestigen dat het werkt, en vervolgens wordt u naar de API verwezen voor de taak die u in gedachten heeft.

note

Er is geen aparte API-referentie. De Axe-account-API-sleutel die u al gebruikt om testresultaten naar de Axe Developer Hub te sturen, werkt ook voor elke Axe Developer Hub-API.

Ontvang uw API-sleutel

Meld u aan bij het Axe Account-portaal.
Kopieer een API-sleutel voor het product dat uw project gebruikt:
- Een Axe Developer Hub-API-sleutel voor web- en CI/CD-projecten.
- Een Axe DevTools Mobile API-sleutel voor mobiele projecten.

Een API-sleutel retourneert alleen gegevens voor zijn eigen product. Een Axe Developer Hub-API-sleutel kan geen Axe DevTools Mobile-gegevens ophalen, en een Axe DevTools Mobile API-sleutel kan geen Axe Developer Hub-gegevens ophalen, zelfs niet voor een organisatiebeheerder. Welke projecten een sleutel binnen zijn product kan openen, hangt af van uw projectlidmaatschap en rol: zie Toegangscontrole in de API-referentie voor sessies en resultaten en de API-referentie voor projecten.

Verstuur de API-sleutel met elke aanvraag

Stuur uw API-sleutel in de X-API-Key-header van elke aanvraag en vraag om een JSON-reactie met de Accept-header:

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

Behandel uw API-sleutel als een geheim: sla deze op in een omgevingsvariabele of in de geheime opslag van uw CI/CD-platform in plaats van deze hard te coderen in uw aanvragen. De voorbeelden in deze handleiding lezen het uit een API_KEY-omgevingsvariabele.

Vind uw project-ID

De meeste aanvragen identificeren een project met behulp van zijn project-ID. U kunt het op twee manieren vinden:

In Axe Developer Hub: Ga naar uw projecten, open het Instellingen-menu voor uw project en selecteer Project configureren. De project-ID verschijnt bovenaan de instructiepagina.
Met de Projects API: Zoek het ID op vanaf de naam van het project. Zie Zoek een project-ID op naam.

Doe uw eerste oproep

Vermeld de projecten waartoe uw API-sleutel toegang heeft. Deze aanvraag heeft geen project-ID nodig, dus het is een snelle manier om te bevestigen dat uw sleutel werkt:

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

Een 200 OK-reactie met een JSON-array van projecten betekent dat uw sleutel geldig en actief is. De project_id van elk project is het ID om te gebruiken in de andere API's. Als u in plaats daarvan 401 Unauthorized krijgt, controleer dan of u de hele sleutel hebt gekopieerd en dat deze bij het product hoort dat uw projecten gebruiken.

Kies uw taak

Beveilig een CI/CD-pijplijn

Gebruik de Commit Status API om een pull-aanvraag of commit te laten mislukken wanneer er toegankelijkheidsfouten worden gevonden. Uw aanvraag geeft een Git-commit-SHA en een project-ID door, en de reactie rapporteert het aantal toegankelijkheidsfouten van die commit's testrun en hoeveel er boven uw a11y-drempel liggen. Uw project moet Git-gegevens gebruiken.

Als uw pijplijn op GitHub draait, gebruik de GitHub-actie in plaats van de API direct aan te roepen.

Verkrijg toegankelijkheidsresultaten

Gebruik de API voor sessies en resultaten om resultaten te downloaden. Roep het Sessions-eindpunt aan om de sessies van een project op te sommen, en geef vervolgens het session_id van een sessie door aan het Results-eindpunt.

Twee gedragingen van het Results-eindpunt beïnvloeden hoe u uw client schrijft:

Resultaten kunnen tijd nodig hebben om voor te bereiden. Een 204 No Content-reactie betekent dat de resultaten nog niet klaar zijn. Wacht kort en herhaal de aanvraag totdat u 200 OK krijgt. Zie Sesionstoestand en het pollingspatroon.
Resultaten downloaden het snelst met Brotli-compressie. Stuur Accept-Encoding: br (of gebruik curl --compressed met een Brotli-ingeschakelde curl), vooral voor format=full. Zie Reactiecompressie.

Beheer projecten en leden

Gebruik de Projects API om je projecten op te sommen, erdoorheen te bladeren of een project-ID te vinden op naam. Je kunt ook projecten aanmaken, bijwerken en verwijderen, en projectleden toevoegen, veranderen of verwijderen. Om dat werk te automatiseren, begin met Aan de slag met projectbeheerautomatisering.

Fouten en Herhalingen Afhandelen

De Axe Developer Hub API's delen een gemeenschappelijke set foutreacties:

Status	Betekenis	Opnieuw proberen?
`400 Bad Request`	Een pad- of queryparameter, of de requestbody, is ongeldig, bijvoorbeeld een verkeerde ID of tijdstempel of een ontbrekend verplicht veld.	Nee. Corrigeer eerst de aanvraag.
`401 Unauthorized`	De API-sleutel is ongeldig of ontbreekt, of het abonnement is inactief.	Nee. Controleer de sleutel en je abonnement.
`403 Forbidden`	De API-sleutel heeft geen toegang tot het gevraagde project of de operatie, bijvoorbeeld het bijwerken van een project waarvan je geen beheerder bent.	Nee. Controleer je projectlidmaatschap of rol, en of je abonnement het projecttype dekt.
`404 Not Found`	Het gevraagde project, de sessie of de commit bestaat niet.	Nee. Controleer de ID of SHA.
`429 Too Many Requests`	Het systeem is zwaar belast.	Ja, na het aantal seconden in de `Retry-After` header.

Wanneer je het Resultaten-eindpunt polst, is 204 No Content geen fout: het betekent dat de resultaten nog niet klaar zijn en dat je dezelfde aanvraag opnieuw doet na een korte wachttijd. Wacht langer tussen herhalingen naarmate je vaker opnieuw probeert, en stop na een redelijke limiet zodat een vastgelopen sessie je pijplijn niet oneindig blokkeert.

Elke referentiepagina vermeldt de exacte foutreacties voor zijn eindpunten. Bouw je herhalingslogica zo dat deze 429 Too Many Requests van elk eindpunt aankan, niet alleen van het Resultaten-eindpunt.