Inizia con le API dell'Hub per Sviluppatori Axe

Ogni API dell'Hub per Sviluppatori Axe utilizza la stessa configurazione: una chiave API dell'Account Axe inviata nell'intestazione della richiesta e, per la maggior parte delle richieste, un ID progetto. Questa guida illustra quella configurazione una volta, effettua una prima chiamata per confermare che funzioni, e poi ti indirizza all'API per il compito che hai in mente.

Ottieni la tua chiave API

1. Accedi al Portale dell'Account Axe.
2. Copia una chiave API per il prodotto utilizzato dal tuo progetto:
   • Una chiave API dell'Hub per Sviluppatori Axe per progetti web e CI/CD.
   • Una chiave API di Axe DevTools Mobile per progetti mobili.

Una chiave API restituisce solo dati per il proprio prodotto. Una chiave API dell'Hub per Sviluppatori Axe non può recuperare i dati di Axe DevTools Mobile, e una chiave API di Axe DevTools Mobile non può recuperare i dati dell'Hub per Sviluppatori Axe, nemmeno per un Amministratore Org. I progetti a cui una chiave può accedere all'interno del suo prodotto dipendono dalla tua appartenenza al progetto e dal tuo ruolo: vedi Controllo Accessi nel Riferimento API di Sessioni e Risultati e nel Riferimento API dei Progetti.

Invia la chiave API con ogni richiesta

Invia la tua chiave API nell'intestazione X-API-Key di ogni richiesta e richiedi una risposta JSON con l'intestazione Accept:

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

Tratta la tua chiave API come un segreto: memorizzala in una variabile d'ambiente o nel deposito segreto della tua piattaforma CI/CD invece di codificarla direttamente nelle tue richieste. Gli esempi in questa guida la leggono da una variabile d'ambiente API_KEY.

Trova il tuo ID progetto

La maggior parte delle richieste identifica un progetto tramite l'ID progetto. Puoi trovarlo in uno dei due modi:

• Nell'Hub per Sviluppatori Axe: Vai al tuo progetti, apri il menu Impostazioni per il tuo progetto e seleziona Configura progetto. L'ID progetto appare in cima alla pagina delle istruzioni.
• Con l'API dei Progetti: Cerca l'ID dal nome del progetto. Vedi Cerca un ID progetto per nome.

Effettua la tua prima chiamata

Elenca i progetti che la tua chiave API può accedere. Questa richiesta non necessita di un ID progetto, quindi è un modo rapido per confermare che la tua chiave funzioni:

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

Una risposta 200 OK con un array JSON di progetti significa che la tua chiave è valida e attiva. L'project_id di ciascun progetto è l'ID da utilizzare nelle altre API. Se ottieni 401 Unauthorized invece, verifica di aver copiato l'intera chiave e che appartenga al prodotto utilizzato dai tuoi progetti.

Scegli il tuo compito

Proteggi una pipeline CI/CD

Usa la API di Stato del Commit per interrompere una richiesta di pull o un commit quando vengono trovati errori di accessibilità. La tua richiesta passa uno SHA di commit Git e un ID progetto, e la risposta riporta il numero di errori di accessibilità dal test di quel commit e quanti superano la tua soglia di accessibilità. Il tuo progetto deve utilizzare dati Git.

Se la tua pipeline funziona su GitHub, usa l'Azione GitHub invece di chiamare direttamente l'API.

Recupera i risultati di accessibilità

Usa la API di Sessioni e Risultati per scaricare i risultati. Chiama l'endpoint Sessions per elencare le sessioni di un progetto, quindi passa l'session_id di una sessione all'endpoint Results.

Due comportamenti dell'endpoint Results influiscono su come scrivi il tuo client:

• I risultati possono impiegare tempo per essere preparati. Una risposta 204 No Content significa che i risultati non sono ancora pronti. Attendi brevemente e ripeti la richiesta finché non ottieni 200 OK. Vedi Stato della Sessione e Modello di Polling.
• I risultati vengono scaricati più velocemente con la compressione Brotli. Invia Accept-Encoding: br (o usa curl --compressed con un curl abilitato Brotli), soprattutto per format=full. Vedi Compressione della Risposta.

Gestisci Progetti e Membri

Usa API dei Progetti per elencare i tuoi progetti, sfogliarli o trovare un ID di progetto per nome. Inoltre, puoi creare, aggiornare e cancellare progetti, e aggiungere, cambiare o rimuovere membri del progetto. Per automatizzare questo lavoro, inizia con Inizia con l'Automazione della Gestione dei Progetti.

Gestire errori e ritentativi

Le API del Axe Developer Hub condividono un insieme comune di risposte di errore:

Quando effettui polling sull'endpoint Risultati, 204 No Content non è un errore: significa che i risultati non sono ancora pronti, e devi ritentare la stessa richiesta dopo una breve attesa. Attendi più a lungo tra un tentativo e l'altro, quanto più volte riprovi, e rinuncia dopo un limite ragionevole affinché una sessione bloccata non blocchi indefinitamente la tua pipeline.

Ogni pagina di riferimento elenca le risposte di errore esatte per i suoi endpoint. Costruisci la tua logica di ritentativo in modo che possa gestire 429 Too Many Requests da qualsiasi endpoint, non solo dall'endpoint Risultati.