Comece com as APIs do Axe Developer Hub

Toda API do Axe Developer Hub usa a mesma configuração: uma chave de API do Axe Account enviada em um cabeçalho de solicitação e, para a maioria das solicitações, um ID de projeto. Este guia percorre essa configuração uma vez, faz uma primeira chamada para confirmar que funciona e, em seguida, direciona você para a API para a tarefa que você tem em mente.

Obtenha Sua Chave de API

1. Faça login no Portal do Axe Account.
2. Copie uma chave de API para o produto que seu projeto usa:
   • Uma chave de API do Axe Developer Hub para projetos web e CI/CD.
   • Uma chave de API do Axe DevTools Mobile para projetos móveis.

Uma chave de API só retorna dados para seu próprio produto. Uma chave de API do Axe Developer Hub não pode recuperar dados do Axe DevTools Mobile, e uma chave de API do Axe DevTools Mobile não pode recuperar dados do Axe Developer Hub, mesmo para um Administrador da Organização. Quais projetos uma chave pode acessar dentro de seu produto depende da sua associação ao projeto e função: veja Controle de Acesso no Referência da API de Sessões e Resultados e na Referência da API de Projetos.

Envie a Chave de API com Cada Solicitação

Envie sua chave de API no cabeçalho X-API-Key de cada solicitação e solicite uma resposta JSON com o cabeçalho Accept:

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

Trate sua chave de API como um segredo: armazene-a em uma variável de ambiente ou no armazenamento de segredos da sua plataforma CI/CD em vez de codificá-la diretamente em suas solicitações. Os exemplos neste guia a leem de uma variável de ambiente API_KEY.

Encontre Seu ID de Projeto

A maioria das solicitações identifica um projeto pelo seu ID de projeto. Você pode encontrá-lo de duas maneiras:

• No Axe Developer Hub: Vá para seus projetos, abra o menu Configurações do seu projeto e selecione Configurar projeto. O ID do projeto aparece no topo da página de instruções.
• Com a API de Projetos: Procure o ID pelo nome do projeto. Veja Procurar um ID de Projeto pelo Nome.

Faça Sua Primeira Chamada

Liste os projetos que sua chave de API pode acessar. Esta solicitação não precisa de um ID de projeto, então é uma maneira rápida de confirmar que sua chave funciona:

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

Uma resposta 200 OK com um array JSON de projetos significa que sua chave é válida e ativa. O project_id de cada projeto é o ID a ser usado nas outras APIs. Se você receber 401 Unauthorized em vez disso, verifique se você copiou a chave inteira e se ela pertence ao produto que seus projetos usam.

Escolha Sua Tarefa

Bloquear um Pipeline CI/CD

Use a API de Status de Commit para falhar um pull request ou commit quando erros de acessibilidade forem encontrados. Sua solicitação passa um SHA de commit do Git e um ID de projeto, e a resposta reporta o número de erros de acessibilidade da execução de teste desse commit e quantos estão além do seu limite de a11y. Seu projeto deve usar dados do Git.

Se o seu pipeline rodar no GitHub, use a Ação do GitHub em vez de chamar a API diretamente.

Recupere Resultados de Acessibilidade

Use a API de Sessões e Resultados para baixar resultados. Chame o endpoint de Sessões para listar as sessões de um projeto, então passe o session_id de uma sessão para o endpoint de Resultados.

Dois comportamentos do endpoint de Resultados afetam como você escreve seu cliente:

• Os resultados podem levar tempo para serem preparados. Uma resposta de 204 No Content significa que os resultados ainda não estão prontos. Espere um pouco e repita a solicitação até que você receba 200 OK. Veja Estado da Sessão e Padrão de Polling.
• Os resultados são baixados mais rapidamente com compressão Brotli. Envie Accept-Encoding: br (ou use curl --compressed com um curl habilitado para Brotli), especialmente para format=full. Veja Compressão de Resposta.

Gerenciar Projetos e Membros

Use o API de Projetos para listar seus projetos, paginá-los ou encontrar um ID de projeto pelo nome. Você também pode criar, atualizar e excluir projetos, além de adicionar, alterar ou remover membros do projeto. Para automatizar esse trabalho, comece com Comece com a Automação de Gerenciamento de Projetos.

Gerenciar Erros e Retentativas

As APIs do Axe Developer Hub compartilham um conjunto comum de respostas de erro:

Quando você consulta o endpoint de Resultados, 204 No Content não é um erro: significa que os resultados ainda não estão prontos, e você deve repetir a mesma solicitação após uma breve espera. Espere mais tempo entre as retentativas quanto mais vezes você tentar, e desista após um limite razoável para que uma sessão travada não bloqueie seu pipeline indefinidamente.

Cada página de referência lista as respostas exatas de erro para seus endpoints. Construa sua lógica de retentativa para que possa lidar com 429 Too Many Requests de qualquer endpoint, não apenas do endpoint de Resultados.