Começando a Desenvolver com Axe DevTools Linter

Este artigo descreve como começar a usar os serviços da API REST fornecidos pela edição local do Axe DevTools Linter ou pelo SaaS Axe DevTools Linter. Os serviços são fornecidos por endpoints REST, por isso é necessário ter experiência com uma ferramenta REST, como Postman, CocoaRestClient ou a extensão REST Client do VS Code. Você também pode acessar os serviços com uma linguagem de programação, como Python.

As diferenças entre as duas edições do Axe DevTools Linter (Axe DevTools Linter SaaS vs. o servidor local) são que a oferta SaaS requer autorização usando uma API a cada solicitação de lint (o endpoint endpoint /lint-source).

Primeiros Passos

Se você está usando a edição SaaS do Axe DevTools Linter Server, primeiro precisa obter uma chave de API. Você pode encontrar as etapas necessárias para obter a chave em Obtendo uma Chave de API SaaS do Axe DevTools Linter.

Para a versão local do Axe DevTools Linter Server, você precisará configurá-lo (conforme detalhado em Instalação do Servidor Axe DevTools Linter Local) e então obter o endereço IP do servidor. Você também precisará da porta na qual o servidor está ouvindo (a padrão é a porta 3000).

Testando Sua Conexão com o curl

Dois dos endpoints REST do Axe DevTools Linter SaaS não requerem autenticação, assim você pode testar sua conexão antes de obter uma chave de API.

Se você quiser realizar um teste simples para verificar se consegue acessar o servidor, pode usar **curl** (ou um navegador web). O exemplo a seguir mostra como usar o endpoint endpoint status do Axe DevTools Linter SaaS:

curl https://axe-linter.deque.com/status

Para a versão local, você digitaria o seguinte:

curl http://<server IP address>:<server port>/status

Você precisa substituir <endereço IP do servidor> e <porta do servidor> no comando acima.

Se o servidor estiver disponível, ele responderá com:

Ok

Você também pode visitar o mesmo URL (por exemplo, https://axe-linter.deque.com/status) com um navegador web e deverá ver o mesmo resultado.

O exemplo a seguir mostra como acessar o endpoint endpoint healthcheck:

curl https://axe-linter.deque.com/healthcheck

O servidor deve responder com o seguinte:

{
  "version": "4.4.0"
}

Assim como com o endpoint endpoint status, você também pode visitar https://axe-linter.deque.com/healthcheck com um navegador web e obter o mesmo resultado que com o curl.

Para verificar a origem de erros de acessibilidade, você precisa criar uma solicitação POST. Você pode usar **curl** ou uma ferramenta como Postman.

No Postman ou outra ferramenta REST, você precisa criar um cabeçalho como o mostrado abaixo:

POST https://axe-linter.deque.com/lint-source
content-type: application/json
authorization: <YOUR API KEY>

Se você estiver usando o Axe DevTools Linter SaaS, precisa substituir por sua chave de API. Se estiver usando o servidor local, não precisa usar o cabeçalho **authorization**, mas precisa mudar o URL para o endereço IP e porta do seu servidor local.

Com **curl**, o cabeçalho equivalente ao mostrado acima seria:

curl --request POST --url https://axe-linter.deque.com/lint-source \
  --header 'content-type: application/json' \
  --header 'authorization: <YOUR API KEY>'

Você também precisa especificar um corpo de requisição como um objeto JSON antes de a requisição ser concluída:

{
  "source": "# Heading\n### Another Heading\n",
  "filename": "file.md"
}

O comando completo **curl** é:

curl --request POST --url https://axe-linter.deque.com/lint-source \
  --header 'content-type: application/json' \
  --header 'authorization: <YOUR API KEY>'
  --data '{ "source": "# Heading\n### Another Heading\n",
    "filename": "file.md" }'

Para o servidor local, você precisa alterar o argumento **--url** e remover a linha **--header 'authorization: <YOUR API KEY>'**.

A seguir, um exemplo de resposta à solicitação acima:

HTTP/1.1 200 OK
Date: Mon, 14 Mar 2022 14:04:19 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 419
Connection: close
X-Powered-By: Express
Surrogate-Control: no-store
Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
Pragma: no-cache
Expires: 0
ETag: W/"1a3-cfgZ30xjvW815mLDpbjoGXreu2o"

{
  "report": {
    "errors": [
      {
        "ruleId": "heading-order",
        "helpURL": "https://dequeuniversity.com/rules/axe/4.4/heading-order?application=axe-linter",
        "description": "Ensures the order of headings is semantically correct",
        "lineContent": "### Another heading",
        "lineNumber": 2,
        "linterType": "md",
        "column": 1,
        "endColumn": 20
      }
    ]
  }
}

Como este exemplo tem um problema de acessibilidade, você recebeu uma resposta que contém um objeto **report** contendo um array **errors** de objetos **error**. Veja Resposta para mais informações sobre este objeto de resposta.

Se a sua chave de API não existir ao usar o Axe DevTools Linter SaaS, você receberá uma resposta assim:

HTTP/1.1 404 Not Found
Date: Fri, 11 Mar 2022 22:38:51 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 33
Connection: close
X-Powered-By: Express
Surrogate-Control: no-store
Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
Pragma: no-cache
Expires: 0
ETag: W/"21-HAVNeHb+a8RfOcMl419aKM67S20"

{
  "error": "No API key found"
}

Nesse caso, você pode tentar recriar sua chave de API ou entrar em contato com o Deque Help Desk para obter ajuda.

Veja Também

• Veja Obtendo uma Chave de API para as etapas necessárias para obter uma chave de API necessária para usar o Axe DevTools Linter SaaS.
• Veja Referência da API REST do Servidor Axe DevTools Linter para uma referência das APIs fornecidas pelo Axe DevTools Linter Server, bem como opções adicionais para o endpoint **linter-source**.
• O Exemplo de Uso da API REST do Axe DevTools Linter contém um uso do curl e um Python que você pode usar com o Axe DevTools Linter Server.