Commencez avec les API du Axe Developer Hub

Chaque API du Axe Developer Hub utilise la même configuration : une clé API du Axe Account envoyée dans un en-tête de requête et, pour la plupart des requêtes, un ID de projet. Ce guide vous guide à travers cette configuration une fois, effectue un premier appel pour confirmer son fonctionnement, puis vous dirige vers l'API adaptée à votre tâche.

Obtenez votre clé API

1. Connectez-vous au Portail Axe Account.
2. Copiez une clé API pour le produit utilisé par votre projet :
   • Une clé API du Axe Developer Hub pour les projets web et CI/CD.
   • Une clé API du Axe DevTools Mobile pour les projets mobiles.

Une clé API ne renvoie les données que pour son propre produit. Une clé API du Axe Developer Hub ne peut pas récupérer les données de Axe DevTools Mobile, et une clé API du Axe DevTools Mobile ne peut pas récupérer des données du Axe Developer Hub, même pour un administrateur d'organisation. Les projets qu'une clé peut accéder au sein de son produit dépendent de votre rôle et de votre appartenance au projet : voir le contrôle d'accès dans le Référence API Sessions et Résultats et le Référence API Projets.

Envoyez la clé API avec chaque requête

Envoyez votre clé API dans l'en-tête X-API-Key de chaque requête, et demandez une réponse JSON avec l'en-tête Accept :

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

Traitez votre clé API comme un secret : stockez-la dans une variable d'environnement ou dans le store secret de votre plateforme CI/CD plutôt que de la coder en dur dans vos requêtes. Les exemples dans ce guide la lisent à partir d'une variable d'environnement API_KEY.

Trouvez votre ID de projet

La plupart des requêtes identifient un projet par son ID de projet. Vous pouvez le trouver de deux façons :

• Dans Axe Developer Hub : Allez à votre projets, ouvrez le menu Paramètres pour votre projet, et sélectionnez Configurer le projet. L'ID de projet apparaît en haut de la page d'instructions.
• Avec l'API Projets : Cherchez l'ID à partir du nom du projet. Voir Chercher un ID de projet par nom.

Effectuez votre premier appel

Listez les projets auxquels votre clé API peut accéder. Cette requête n'a pas besoin d'un ID de projet, c'est donc un moyen rapide de confirmer que votre clé fonctionne :

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

Une réponse 200 OK avec un tableau JSON de projets signifie que votre clé est valide et active. L'project_id de chaque projet est l'ID à utiliser dans les autres APIs. Si vous recevez 401 Unauthorized à la place, vérifiez que vous avez bien copié la clé entière et qu'elle appartient au produit que vos projets utilisent.

Choisissez votre tâche

Protéger un pipeline CI/CD

Utilisez l'API de statut de commit pour refuser une pull request ou un commit lorsque des erreurs d'accessibilité sont trouvées. Votre requête transmet une SHA de commit Git et un ID de projet, et la réponse indique le nombre d'erreurs d'accessibilité à partir de l'exécution de test de ce commit et combien dépassent votre seuil d'accessibilité. Votre projet doit utiliser les données Git.

Si votre pipeline s'exécute sur GitHub, utilisez l'Action GitHub plutôt que d'appeler directement l'API.

Récupérer les résultats d'accessibilité

Utilisez l'API Sessions et Résultats pour télécharger les résultats. Appelez le point de terminaison Sessions pour lister les sessions d'un projet, puis passez l'session_id d'une session au point de terminaison des Résultats.

Deux comportements du point de terminaison des Résultats affectent la manière dont vous écrivez votre client :

• Les résultats peuvent prendre du temps à se préparer. Une réponse 204 No Content signifie que les résultats ne sont pas encore prêts. Attendez brièvement et répétez la requête jusqu'à ce que vous receviez 200 OK. Voir État de la session et modèle de sondage.
• Les résultats se téléchargent plus rapidement avec la compression Brotli. Envoyez Accept-Encoding: br (ou utilisez curl --compressed avec un curl activé pour Brotli), surtout pour format=full. Voir Compression de la réponse.

Gérer les projets et les membres

Utilisez le API Projets pour lister vos projets, naviguer parmi eux ou trouver un ID de projet par nom. Vous pouvez également créer, mettre à jour et supprimer des projets, et ajouter, modifier ou supprimer des membres de projet. Pour automatiser ce travail, commencez avec Commencez avec l'automatisation de la gestion de projet.

Gérer les erreurs et les réessais

Les API du Axe Developer Hub partagent un ensemble commun de réponses d'erreurs :

Lorsque vous interrogez le point de terminaison des résultats, 204 No Content n’est pas une erreur : cela signifie que les résultats ne sont pas encore prêts, et vous réessayez la même requête après un court délai. Patientez plus longtemps entre les tentatives si vous réessayez plusieurs fois, et abandonnez après une limite raisonnable pour qu'une session bloquée ne retienne pas votre pipeline indéfiniment.

Chaque page de référence répertorie les réponses d'erreurs exactes pour ses points de terminaison. Construisez votre logique de réessai pour qu'elle puisse gérer 429 Too Many Requests à partir de n'importe quel point de terminaison, pas seulement le point de terminaison des résultats.