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), HTL (.htl) e Markdown (.md e .markdown).

Os Endpoints REST

O servidor fornece seis endpoints REST. O primeiro endpoint, (/lint-source), responde a solicitações POST e verifica seu código quanto a problemas de acessibilidade. O segundo endpoint, (/status), responde a solicitações GET 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 solicitações GET, indica 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 de Lint (/lint-source)

O endpoint de lint é o principal endpoint de serviço. Você pode usá-lo para enviar código ao Axe DevTools Linter para verificar problemas de acessibilidade. Ele aceita solicitações POST 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 de lint do servidor, conforme 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 Obtendo 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 de cabeçalho têm uma lacuna 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 a este erro, veja 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:

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

A string language pode assumir um dos seguintes valores:

O servidor usa as propriedades filename e language para determinar qual linter usar. Normalmente, o 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, pode usar a propriedade language e os valores especificados na tabela acima. Nesse caso, você ainda deve especificar um filename como um parâmetro obrigatório, mas language tem precedência sobre a extensão do nome do arquivo. Por exemplo, se você especificar um filename de "somefile.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 JSON de resposta para uma fonte que possui um erro (observe que errors é uma matriz 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

A matriz errors contém objetos error, que têm as seguintes propriedades:

O Objeto config

Você pode especificar uma propriedade config se quiser mais controle sobre as regras que o Axe DevTools Linter usa para verificar sua fonte quanto a erros de acessibilidade.

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

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

O Objeto global-components

O objeto global-components mapeia componentes personalizados e seus atributos para elementos e atributos HTML existentes. Para informações introdutórias sobre a verificação de lint em componentes personalizados, veja 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, veja O Valor Especial <text>.

O valor especial aria-* 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 propriedade replace indica se custom-component deve ser removido da árvore DOM de saída, que elementos personalizados Angular e JavaScript incluem. O padrão é o mesmo que o padrão para a tecnologia utilizada. Ou seja, true para Angular e HTML, false para JSX, TSX e Vue.

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

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

A Propriedade rules

A propriedade rules referencia um objeto LinterRuleset, que permite habilitar ou desabilitar 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 seguinte configuração habilita a regra image-alt e desabilita 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 Propriedade exclude

A propriedade exclude pode ser usada para informar ao Axe Linter para ignorar certos arquivos ao verificar. Veja Arquivo de Configuração na documentação do Conector Axe DevTools Linter para mais informações.

A Propriedade tags

A propriedade tags é uma matriz de strings ou tags. Cada tag é vinculada a uma ou mais regras de acessibilidade, assim, ao especificar várias tags aqui, você pode habilitar muitas regras de acessibilidade diferentes (e desabilitar qualquer regra que não esteja marcada com as tags especificadas). As tags geralmente 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 execução e retornar seu número de versão, envie uma solicitação GET para o endpoint de verificação de saúde. Um exemplo de solicitação está 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 Cobrança Empresarial (/billing/enterprise)

O endpoint de cobrança empresarial permite que você obtenha informações totais de uso para a sua empresa e o uso detalhado por chaves de API individuais. O endpoint responde a uma solicitação GET e requer que você especifique um ano e 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 dados de um mês, mas você pode usar a string de consulta months=<number-of-months-data> opcional para especificar mais. O parâmetro months pode variar de 1 a 12 (inclusive). O exemplo abaixo mostra como obter dados de três meses 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 linter SaaS responde com um objeto JSON que contém dois objetos. O primeiro é um objeto summary, e o segundo, api_keys, é uma coleção de objetos que contêm informações sobre o uso do serviço 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 Objeto summary

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

O Array api_keys

O array api_keys contém objetos compostos pelas seguintes propriedades:

O Endpoint de Cobrança 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 de API fornecida (no cabeçalho authorization):

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

Como os outros endpoints de cobrança, você pode especificar uma string de consulta months 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 Objeto summary e O Array api_keys acima.

O Endpoint de Cobrança da Chave de 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 cobrança, você pode especificar uma string de consulta months 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 houveram linhas analisadas durante o período especificado usando a chave de API especificada no cabeçalho Authorization, você receberá 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 especificado e o número total de verificações que foram iniciadas por esta chave de API no período 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 os passos necessários para obter uma chave de API.