Referencia de la API REST de Axe DevTools Linter

Axe DevTools Linter te permite verificar el código en busca de problemas de accesibilidad mediante una API REST. Creas un objeto de solicitud HTTP que contiene las líneas de código que deseas verificar (en el cuerpo de la solicitud como un objeto JSON), y el servidor devuelve un objeto JSON de respuesta que indica cualquier problema de accesibilidad que el servidor encuentre.

El servidor puede verificar archivos de React (.js, .jsx, .ts y .tsx), Vue (.vue), Angular (.component.html), HTML (.html, .htm y .xhtml), LiquidJS (.liquid), HTL (.htl) y Markdown (.md y .markdown).

Los puntos finales REST

El servidor proporciona seis puntos finales REST. El primer punto final, (/lint-source), responde a solicitudes POST y verifica tu código en busca de problemas de accesibilidad. El segundo punto final, (/status), responde a solicitudes GET y muestra si el servidor está disponible con un código de respuesta 200 que indica que el servidor está escuchando. El tercer punto final, (/healthcheck), responde a solicitudes GET, indica si el servidor está en funcionamiento y devuelve el número de versión del servidor en ejecución. Los tres puntos finales restantes permiten a los usuarios de la edición SaaS obtener información de uso para su empresa en su conjunto (/billing/enterprise), sus usuarios (/billing/user) y sus claves API (/billing/key).

Los puntos finales REST son los siguientes:

El Punto Final de Lint (/lint-source)

El punto final de lint es el principal servicio de punto final. Puedes usarlo para enviar código a Axe DevTools Linter para verificar problemas de accesibilidad. Acepta solicitudes POST con un cuerpo JSON que contiene el código a verificar.

Solicitud

Para utilizar este punto final, creas una solicitud POST hacia el punto final lint del servidor, como se muestra en el ejemplo a continuación:

POST /lint-source

También debes incluir un encabezado Content-Type para indicar al servidor que el cuerpo de la solicitud contiene un objeto JSON.

Content-Type: application/json

Si estás utilizando Axe DevTools Linter SaaS, necesitarás incluir un encabezado Authorization con tu clave API, como se muestra a continuación:

Authorization: <YOUR API KEY>

Puedes aprender más sobre cómo obtener una clave API en Obteniendo una Clave API de Axe DevTools Linter SaaS.

El cuerpo de la solicitud debe contener el código (dentro de un objeto JSON) que deseas verificar. Por ejemplo, el siguiente objeto JSON verifica una muestra de markdown:

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

La muestra de Markdown anterior tiene un error de accesibilidad: hay una brecha entre los niveles de encabezado entre el primer encabezado (nivel 1) y el segundo encabezado (nivel 3). Para ver la respuesta del servidor a este error, consulta la sección Respuesta a continuación.

El Objeto de Solicitud JSON

La siguiente tabla muestra las propiedades utilizadas con el objeto de solicitud JSON:

La cadena source en el objeto JSON de solicitud es el código que deseas verificar. Debes escapar todas las comillas y las nuevas líneas (precederlas con una barra invertida).

La cadena language puede tomar uno de los siguientes valores:

El servidor utiliza las propiedades filename y language para determinar qué linter usar. Generalmente, Axe DevTools Linter usará la extensión del archivo en la propiedad filename para elegir el linter. Si prefieres especificar el linter que se debe usar, puedes utilizar la propiedad language y los valores especificados en la tabla anterior. En este caso, todavía debes especificar un filename como un parámetro requerido, pero language tiene prioridad sobre la extensión del nombre de archivo. Por ejemplo, si especificas un filename de "somefile.html" y un language de md, el servidor utilizará el linter de Markdown.

Respuesta

El servidor responde con un código de respuesta 200 haya o no errores de accesibilidad. Necesitas examinar el JSON en el cuerpo de la respuesta para ver si hay errores.

Si el código no tiene errores, el objeto de respuesta JSON es el siguiente:

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

El siguiente ejemplo muestra el objeto JSON de respuesta para una fuente que tiene un error (note que errors es un 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
      }
    ]
  }
}

El Objeto error

El array errors contiene objetos error, los cuales tienen las siguientes propiedades:

El Objeto config

Puedes especificar una propiedad config si deseas tener más control sobre las reglas que Axe DevTools Linter usa para verificar tu fuente en busca de errores de accesibilidad.

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

El ejemplo anterior muestra que, aunque la fuente tenga un error de accesibilidad (la falta de un atributo lang en el elemento html), no se devolverán errores porque esa regla ha sido desactivada.

El Objeto global-components

El objeto global-components mapea componentes personalizados y sus atributos a elementos y atributos HTML existentes. Para obtener información introductoria sobre el análisis de componentes personalizados, consulta Análisis de Componentes Personalizados.

El siguiente ejemplo muestra un mapeo completo de un 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
    }
  }
}

El ejemplo muestra el mapeo del componente personalizado custom-component a html-element con atributos custom-attribute-1 mapeados a html-element-attribute1 y custom-attribute-2 mapeados a <text>, que es un valor especial de atributo que mapea custom-attribute-2 al contenido de texto del elemento HTML de salida. Para más información, consulta El Valor Especial <text>.

El valor especial aria-* indica que todos los atributos ARIA en el elemento personalizado deben ser copiados al elemento HTML de salida. Consulta Usando aria-* para más información.

La propiedad replace indica si custom-component debe eliminarse del árbol DOM de salida, lo cual incluyen Angular y elementos personalizados de JavaScript. El valor predeterminado es el mismo que el predeterminado para la tecnología utilizada. Es decir, true para Angular y HTML, false para JSX, TSX y Vue.

Si el componente personalizado no requiere mapeo de atributos, puedes usar este formato abreviado que mapea custom-component a html-element:

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

La Propiedad rules

La propiedad rules referencia un objeto LinterRuleset, lo cual te permite habilitar o deshabilitar reglas por su ID de regla. Para más información sobre las reglas de accesibilidad, consulta Reglas de Accesibilidad del Linter Axe DevTools.

Por ejemplo, la siguiente configuración habilita la regla image-alt y deshabilita la regla tabindex:

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

Para ver una lista de reglas que el servidor verifica, consulte Reglas de accesibilidad de Axe DevTools Linter

La propiedad exclude

La propiedad exclude se puede utilizar para indicarle a Axe Linter que omita ciertos archivos durante el análisis. Vea Archivo de configuración en la documentación del Conector de Axe DevTools Linter para más información.

La propiedad tags

La propiedad tags es un arreglo de cadenas o etiquetas. Cada etiqueta está vinculada a una o más reglas de accesibilidad, por lo que al especificar varias etiquetas aquí, puede habilitar muchas reglas de accesibilidad diferentes (y deshabilitar cualquier regla que no esté etiquetada con las etiquetas especificadas). Las etiquetas suelen corresponder a diferentes estándares de accesibilidad, y cada regla puede ser miembro de muchas etiquetas diferentes.

El punto de acceso de estado (/status)

El punto de acceso de comprobación de salud (/healthcheck)

Para verificar si el servidor está en funcionamiento y devolver su número de versión, envíe una solicitud GET al punto de acceso de comprobación de salud. A continuación se muestra un ejemplo de solicitud:

GET /healthcheck

Si el servidor está en funcionamiento, responderá con el número de versión del servidor, como se muestra en el ejemplo a continuación:

{
  "version": "4.10.3"
}

El punto de acceso de facturación empresarial (/billing/enterprise)

El punto de acceso de facturación empresarial le permite obtener información del uso total para su empresa y el uso desglosado por claves de API individuales. El punto de acceso responde a una solicitud GET y requiere que especifique un año y mes (aquí, mayo de 2022), como se muestra a continuación:

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

La solicitud requiere un encabezado authorization con su clave API. Vea Obtener una clave API para más información.

Por defecto, el servidor devuelve un mes de datos, pero puede usar la cadena de consulta months=<number-of-months-data> opcional para especificar más. El parámetro months puede variar de 1 a 12 (inclusive). El siguiente ejemplo muestra cómo obtener tres meses de datos comenzando en mayo de 2022:

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

Respuesta

El servidor linter SaaS responde con un objeto JSON que contiene dos objetos. El primero es un objeto summary, y el segundo, api_keys, es una colección de objetos que contienen información sobre el uso del servicio linter de cada clave API.

A continuación se muestra un ejemplo de objeto de respuesta:

{
  "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
  }]
}

Si no hay datos para el período de tiempo especificado, la respuesta sería así:

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

El objeto summary

El objeto summary le proporciona información sobre el número total de líneas analizadas y cuántos escaneos fueron iniciados por usuarios dentro de la empresa.

El arreglo api_keys

El arreglo api_keys contiene objetos compuestos por las siguientes propiedades:

El Endpoint de Facturación del Usuario (/billing/user)

Este endpoint, el endpoint de facturación de uso, le permite obtener información de facturación para un usuario para todas las claves API utilizadas para acceder al servidor SaaS. El valor predeterminado es que se devuelvan los datos de un mes.

El siguiente ejemplo muestra una solicitud para mayo de 2022 para el usuario representado por la clave API proporcionada (en el encabezado authorization):

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

Al igual que con los otros endpoints de facturación, puede especificar una cadena de consulta opcional months como se muestra a continuación:

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

A continuación se muestra un ejemplo de objeto de respuesta:

{
  "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
  }]
}

Si el usuario no tuvo uso para el período de tiempo especificado, recibiría esta respuesta:

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

El objeto de respuesta contiene dos objetos, summary y api_keys pertenecientes al usuario. Para más información, vea El Objeto summary y El Array api_keys arriba.

El Endpoint de Facturación por Clave API (/billing/key)

Para obtener datos de uso de una clave API, puede utilizar el endpoint de facturación por clave API. Necesita especificar el año y el mes como se muestra a continuación:

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

Al igual que con los otros endpoints de facturación, puede especificar una cadena de consulta opcional months como se muestra a continuación:

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

A continuación se muestra un ejemplo de objeto de respuesta:

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

Si no hubo líneas revisadas durante el período de tiempo especificado utilizando la clave API especificada en el encabezado Authorization, recibiría una respuesta como la siguiente:

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

El valor name es el nombre asignado a la clave API cuando fue creada. Los otros valores, total_lines_linted y total_scans, especifican el número de líneas que fueron revisadas en el período de tiempo especificado y el número total de escaneos que fueron iniciados por esta clave API en el período de tiempo especificado.

Referencia Rápida de URLs

Las URLs importantes para usar con Axe DevTools Linter SaaS son las siguientes:

Consulte Obteniendo una Clave API de Axe DevTools Linter SaaS para más información sobre los pasos necesarios para obtener una clave API.