Referência da API REST do Axe DevTools Linter

O Axe DevTools Linter permite verificar o código em busca de problemas de acessibilidade usando uma API REST. Você cria um objeto de solicitação HTTP que contém as linhas de código que deseja verificar (no corpo da solicitação como um objeto JSON), e o servidor retorna um objeto JSON de resposta que indica qualquer problema de acessibilidade encontrado pelo servidor.

O servidor pode verificar arquivos React (.js, .jsx, .ts e .tsx), Vue (.vue), Angular (.component.html), HTML (.html, .htm e .xhtml), LiquidJS (.liquid) e Markdown (.md e .markdown).

Os Endpoints REST

O servidor fornece seis endpoints REST. O primeiro endpoint, (/lint-source), responde a POST solicitações e verifica seu código em busca de problemas de acessibilidade. O segundo endpoint, (/status), responde a GET solicitações e mostra se o servidor está disponível com um código de resposta 200 indicando que o servidor está ouvindo. O terceiro endpoint, (/healthcheck), responde a GET solicitações, indicando se o servidor está em execução, e retorna o número da versão do servidor em execução. Os três endpoints restantes permitem que os usuários da edição SaaS obtenham informações de uso para sua empresa como um todo (/billing/enterprise), seus usuários (/billing/user) e suas chaves de API (/billing/key).

Os endpoints REST são os seguintes:

O Endpoint Lint (/lint-source)

O endpoint lint é o endpoint principal do serviço. Você pode usá-lo para enviar código ao Axe DevTools Linter para verificar problemas de acessibilidade. Ele aceita POST solicitações com um corpo JSON contendo o código a ser verificado.

Solicitação

Para usar este endpoint, você cria uma solicitação POST para o endpoint lint do servidor, como mostrado no exemplo abaixo:

POST /lint-source

Você também deve incluir um cabeçalho Content-Type para informar ao servidor que o corpo da solicitação contém um objeto JSON.

Content-Type: application/json

Se você estiver usando o Axe DevTools Linter SaaS, precisará incluir um cabeçalho Authorization com sua chave de API, conforme mostrado abaixo:

Authorization: <YOUR API KEY>

Você pode saber mais sobre como obter uma chave de API em Obter uma Chave de API do Axe DevTools Linter SaaS.

O corpo da solicitação deve conter o código (dentro de um objeto JSON) que você deseja verificar. Por exemplo, o seguinte objeto JSON verifica um exemplo de Markdown:

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

O exemplo de Markdown acima tem um erro de acessibilidade: os níveis dos cabeçalhos têm um intervalo entre o primeiro cabeçalho (nível de cabeçalho 1) e o segundo cabeçalho (nível de cabeçalho 3). Para ver a resposta do servidor para este erro, consulte a seção Resposta abaixo.

O Objeto de Solicitação JSON

A tabela a seguir mostra as propriedades usadas com o objeto de solicitação JSON:

O source string no objeto JSON da solicitação é o código que você deseja verificar. Você precisa escapar todas as aspas e quebras de linha (preceda com uma barra invertida).

O language string pode assumir um dos seguintes valores:

O servidor usa as propriedades filename e language para determinar qual linter usar. Normalmente, Axe DevTools Linter usará a extensão do arquivo na propriedade filename para escolher o linter. Se você quiser especificar o linter a ser usado, em vez disso, pode usar a propriedade language e os valores especificados na tabela acima. Neste caso, você ainda deve especificar um filename como um parâmetro necessário, mas language tem precedência sobre a extensão do nome do arquivo. Por exemplo, se você especificar um filename de "algumarquivo.html" e um language de md, o servidor usará o linter de Markdown.

Resposta

O servidor responde com um código de resposta de 200, independentemente de haver ou não erros de acessibilidade. Você precisa examinar o JSON no corpo da resposta para ver se há erros.

Se o código não tiver erros, o objeto de resposta JSON é o seguinte:

{
  "report": {
    "errors": []
  }
}

O exemplo a seguir mostra o objeto de resposta JSON para um código que tem um erro (note que errors é um array de objetos error ).

{
  "report": {
    "errors": [
      {
        "ruleId": "heading-order",
        "helpURL": "https://dequeuniversity.com/rules/axe/4.3/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
      }
    ]
  }
}

O Objeto error Objeto

O array errors armazena objetos error , que possuem as seguintes propriedades:

O config Objeto

Você pode especificar uma propriedade config se quiser ter mais controle sobre as regras que o Axe DevTools Linter usa para verificar seu código fonte em busca de erros de acessibilidade.

{
  "source": "<html></html>",
  "filename": "file.html",
  "config": {
    "rules": {
      "html-has-lang": false
    },
    "exclude": [],
    "tags": []
  }
}

O exemplo anterior mostra que, embora o código-fonte tenha um erro de acessibilidade (um lang atributo ausente no html elemento), nenhum erro será retornado porque essa regra foi desativada.

O global-components Objeto

O global-components objeto mapeia componentes personalizados e seus atributos para elementos e atributos HTML existentes. Para obter informações introdutórias sobre linting de componentes personalizados, consulte Linting de Componentes Personalizados.

O exemplo a seguir mostra um mapeamento completo de componente personalizado:

{
  "config": {
    "global-components": {
      "custom-component": {
        "element": "html-element",
        "attributes": [
          { "custom-attribute-1": "html-element-attribute-1" },
          { "custom-attribute-2": "<text>" },
          "aria-*"
        ],
        "replace": true
    }
  }
}

O exemplo mostra o mapeamento do componente personalizado custom-component para html-element com atributos custom-attribute-1 mapeados para html-element-attribute1 e custom-attribute-2 mapeados para <text>, que é um valor de atributo especial que mapeia custom-attribute-2 para o conteúdo de texto do elemento HTML de saída. Para mais informações, consulte O Especial <text> Valor.

O aria-* valor especial indica que todos os atributos ARIA no elemento personalizado devem ser copiados para o elemento HTML de saída. Veja Usando aria-* para mais informações.

A replace propriedade indica se custom-component deve ser removido da árvore DOM de saída, que inclui elementos personalizados Angular e JavaScript. O padrão é o mesmo que o padrão para a tecnologia utilizada. Isto é, true para Angular e HTML, false para JSX, TSX e Vue.

Se o componente personalizado não requer mapeamento de atributos, você pode usar este formato abreviado que mapeia custom-component para html-element:

{
  "config": {
    "global-components": {
      "custom-component": "html-element"
    }
  }
}

A rules Propriedade

A rules propriedade referencia um LinterRuleset objeto, que permite ativar ou desativar regras pelo ID da regra. Para mais informações sobre as regras de acessibilidade, veja Regras de Acessibilidade do Axe DevTools Linter.

Por exemplo, a configuração a seguir ativa a regra image-alt e desativa a regra tabindex :

{
  "config": {
    "rules": {
      "image-alt": true,
      "tabindex": false
    }
  }
}

Para uma lista de regras contra as quais o servidor verifica, veja Regras de Acessibilidade do Axe DevTools Linter

A exclude Propriedade

A exclude propriedade pode ser usada para informar o Axe Linter para ignorar certos arquivos durante a análise. Veja Arquivo de Configuração na documentação do Axe DevTools Linter Connector para mais informações.

A tags Propriedade

A tags *tags* tags. Cada tag é anexada a uma ou mais regras de acessibilidade, assim, especificando várias tags aqui, você pode ativar muitas regras de acessibilidade diferentes (e desativar quaisquer regras que não estejam etiquetadas com as tags especificadas). As tags normalmente correspondem a diferentes padrões de acessibilidade, e cada regra pode ser membro de muitas tags diferentes.

O Endpoint de Status (/status)

O Endpoint de Verificação de Saúde (/healthcheck)

Para verificar se o servidor está em funcionamento e retornar seu número de versão, envie uma GET solicitação para o endpoint de verificação de saúde. Um exemplo de solicitação é mostrado abaixo:

GET /healthcheck

Se o servidor estiver em funcionamento, ele responderá com o número da versão do servidor, conforme mostrado no exemplo abaixo:

{
  "version": "4.10.3"
}

O Endpoint de Faturamento Empresarial (/billing/enterprise)

O endpoint de faturamento empresarial permite obter informações de uso total para sua empresa e o uso dividido por chaves de API individuais. O endpoint responde a uma GET solicitação e requer que você especifique um ano e um mês (aqui, maio de 2022), conforme mostrado abaixo:

GET https://axe-linter.deque.com/billing/enterprise/2022/4
authorization: <YOUR-API-KEY>

A solicitação requer um cabeçalho authorization com sua chave de API. Veja Obtendo uma Chave de API para mais informações.

Por padrão, o servidor retorna um mês de dados, mas você pode usar a months=<number-of-months-data> string de consulta opcional para especificar mais. O months parâmetro pode variar de 1 a 12 (inclusivo). O exemplo abaixo mostra uma obtenção de três meses de dados começando em maio de 2022:

GET https://axe-linter.deque.com/billing/enterprise/2022/4?months=3
authorization: <YOUR-API-KEY>

Resposta

O servidor SaaS linter responde com um objeto JSON que contém dois objetos. O primeiro é um summary objeto, e o segundo, api_keys, é uma coleção de objetos que contém informações sobre o uso do serviço de linter por cada chave de API.

Um exemplo de objeto de resposta é mostrado abaixo:

{
  "summary": {
    "year": 2022,
    "month": 5,
    "total_lines_linted": 500,
    "total_scans": 40
  },
  "api_keys": [{
    "id": "a2fd58d0-4810-4fbb-b928-7befa01bf89c",
    "name": "My Project",
    "keycloak_id": "d117bb33-1308-41b0-8960-06301eefb169",
    "user_email": "someone@example.com",
    "total_lines_linted": 500,
    "total_scans": 40
  }]
}

Se não houver dados para o período especificado, a resposta pareceria assim:

{
  "summary": {
    "year": 2022,
    "month": 5
  },
  "api_keys": []
}

O summary Objeto

O summary objeto fornece informações sobre o número total de linhas analisadas e quantas verificações foram iniciadas por usuários dentro da empresa.

O api_keys Array

A api_keys matriz contém objetos compostos pelas seguintes propriedades:

O Endpoint de Faturamento do Usuário (/billing/user)

Este endpoint, o endpoint de faturamento de uso, permite obter informações de faturamento para um usuário para todas as chaves da API usadas para acessar o servidor SaaS. O padrão é retornar os dados de um mês.

O exemplo a seguir mostra uma solicitação para maio de 2022 para o usuário representado pela chave da API fornecida (no authorization cabeçalho):

GET https://axe-linter.deque.com/billing/user/2022/4
authorization: <YOUR-API-KEY>

Como os outros endpoints de faturamento, você pode especificar uma months string de consulta opcional conforme mostrado abaixo:

GET https://axe-linter.deque.com/billing/user/2022/4?months=2
authorization: <YOUR-API-KEY>

O seguinte mostra um exemplo de objeto de resposta:

{
  "summary": {
    "year": 2022,
    "month": 5,
    "total_lines_linted": 500,
    "total_scans": 40
  },
  "api_keys": [{
    "id": "a2fd58d0-4810-4fbb-b928-7befa01bf89c",
    "name": "My Project",
    "keycloak_id": "d117bb33-1308-41b0-8960-06301eefb169",
    "user_email": "someone@example.com",
    "total_lines_linted": 500,
    "total_scans": 40
  }]
}

Se o usuário não teve uso no período especificado, você receberia esta resposta:

{
  "summary": {
    "year": 2022,
    "month": 5
  },
  "api_keys": []
}

O objeto de resposta contém dois objetos, summary e api_keys pertencentes ao usuário. Para mais informações, veja O summary Objeto e O api_keys Array acima.

O Endpoint de Faturamento da Chave da API (/billing/key)

Para obter dados de uso de uma chave da API, você pode usar o endpoint de faturamento da chave da API. Você precisa especificar o ano e o mês conforme mostrado abaixo:

GET https://axe-linter.deque.com/billing/key/2022/4
authorization: <YOUR-API-KEY>

Como os outros endpoints de faturamento, você pode especificar uma months string de consulta opcional conforme mostrado abaixo:

GET https://axe-linter.deque.com/billing/key/2022/4?months=2
authorization: <YOUR-API-KEY>

Um exemplo de objeto de resposta é mostrado abaixo:

{
  "name": "My Project",
  "total_lines_linted": 1000,
  "total_scans": 200
}

Se não houvesse linhas analisadas durante o período especificado usando a chave da API especificada no Authorization cabeçalho, você receberia uma resposta como a seguinte:

{
  "name": "My Project",
  "total_lines_linted": 0,
  "total_scans": 0
}

O valor name é o nome atribuído à chave de API quando foi criada. Os outros valores, total_lines_linted e total_scans, especificam o número de linhas que foram analisadas no período de tempo especificado e o número total de varreduras que foram iniciadas por esta chave de API no período de tempo especificado.

Referência Rápida de URLs

As URLs importantes para uso com Axe DevTools Linter SaaS são as seguintes:

Veja Obtendo uma Chave de API do Axe DevTools Linter SaaS para mais informações sobre as etapas necessárias para obter uma chave de API.