Referencia de API REST de axe DevTools Linter

Axe DevTools Linter le permite verificar el código en busca de problemas de accesibilidad utilizando una API REST. Se crea un objeto de solicitud HTTP que contiene las líneas de origen que desea 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 encuentre el servidor.

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

Los puntos de acceso REST

El servidor proporciona seis puntos finales REST. El primer punto final, (/lint-source), responde a las POST solicitudes y verifica su código para detectar problemas de accesibilidad. El segundo punto final, (/status), responde a las GET solicitudes 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 las GET solicitudes, indica si el servidor está en ejecución 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 de 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 punto final del servicio principal. Puedes usarlo para enviar código a axe DevTools Linter para verificar problemas de accesibilidad. Acepta solicitudes con un cuerpo JSON que contiene el código a comprobar. POST

Petición

Para utilizar este endpoint, debe crear una solicitud al endpoint lint del servidor, como se muestra en el siguiente ejemplo: POST

POST /lint-source

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

Content-Type: application/json

Si está utilizando axe DevTools Linter SaaS, deberá incluir un encabezado con su clave API, como se muestra a continuación: Authorization

Authorization: <YOUR API KEY>

Puede obtener más información sobre cómo obtener una clave API en Obtener una clave API de axe DevTools Linter SaaS.

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

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

El ejemplo de Markdown anterior tiene un error de accesibilidad: los niveles de encabezado tienen un espacio entre el primer encabezado (nivel de encabezado 1) y el segundo encabezado (nivel de encabezado 3). Para ver la respuesta del servidor a este error, consulte 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 la solicitud es el código que desea verificar. Debes escapar todas las comillas y nuevas líneas (precederlas con una barra invertida).

La cadena puede tomar uno de los siguientes valores: language

El servidor utiliza las propiedades filename y language para determinar qué linter utilizar. Generalmente, axe DevTools Linter utilizará la extensión de archivo en la propiedad filename para elegir el linter. Si desea especificar el linter a utilizar en su lugar, puede utilizar la propiedad language y los valores especificados en la tabla anterior. En este caso, aún debe especificar a filename como parámetro obligatorio, pero language tiene prioridad sobre la extensión del nombre del archivo. Por ejemplo, si especifica un filename de "somefile.html" y un language de md valor, el servidor utilizará el linter de Markdown.

Respuesta

El servidor responde con un código de respuesta 200 independientemente de que haya o no errores de accesibilidad. Debe 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 la fuente que tiene un error (tenga en cuenta que errors es una matriz de error objetos).

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

errors La matriz contiene error objetos que tienen las siguientes propiedades:

El objeto config

Puede especificar una propiedad si desea tener más control sobre las reglas que axe DevTools Linter utiliza para verificar su fuente en busca de errores de accesibilidad. config

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

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

El objeto global-components

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

El siguiente ejemplo muestra una asignación completa de componentes personalizados:

{
  "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 la asignación del componente personalizado custom-component a html-element con atributos custom-attribute-1 asignados a html-element-attribute1 y custom-attribute-2 asignados a <text>, que es un valor de atributo especial que se asigna custom-attribute-2 al contenido de texto del elemento HTML de salida. Para obtener más información, consulte El valor especial <text>.

El especial aria-* value indicates that all ARIA attributes on the custom element should be copied to the output HTML element. See Using aria-* para más información.

La propiedad replace indica si custom-component debe eliminarse del árbol DOM de salida, que incluye los elementos personalizados de Angular y 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 asignación de atributos, puede usar este formato abreviado que asigna a custom-component : html-element

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

La propiedad rules

rules La propiedad hace referencia a LinterRuleset un objeto, que le permite habilitar o deshabilitar reglas según su ID de regla. Para obtener más información sobre las reglas de accesibilidad, consulte axe DevTools Linter Accessibility Rules.

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

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

Para obtener una lista de las reglas que verifica el servidor, consulte axe DevTools Linter Accessibility Rules

La propiedad exclude

La propiedad exclude se puede usar para indicarle a axe DevTools Linter que omita ciertos archivos al realizar el análisis. Consulte Archivo de configuración en la documentación de axe DevTools Linter Connector para obtener más información.

La propiedad tags

La propiedad es una matriz de cadenas o etiquetas. tags ** Cada etiqueta está asociada 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 generalmente corresponden a diferentes estándares de accesibilidad y cada regla puede ser miembro de muchas etiquetas diferentes.

El punto final de estado (/status)

El endpoint de comprobación del estado (/healthcheck)

Para comprobar si el servidor está en ejecución y devolver su número de versión, envíe una solicitud al endpoint de comprobación de estado. GET A continuación se muestra un ejemplo de solicitud:

GET /healthcheck

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

{
  "version": "4.10.3"
}

El endpoint de facturación empresarial (/billing/enterprise)

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

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

La solicitud requiere un encabezado con su clave API. authorization Consulte Obtención de una clave API para obtener más información.

De forma predeterminada, el servidor devuelve un mes de datos, pero puede utilizar la cadena de consulta opcional months=<number-of-months-data> para especificar más. El parámetro months puede variar de 1 a 12 (inclusive). El siguiente ejemplo muestra un ejemplo de obtención de tres meses de datos a partir de 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 summary un objeto, y el segundo, api_keysuna colección de objetos que contienen información sobre el uso que cada clave API hace del servicio linter.

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 se vería así:

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

El objeto summary

El objeto summary le brinda información sobre la cantidad total de líneas analizadas y cuántos análisis iniciaron los usuarios dentro de la empresa.

La matriz api_keys

La matriz contiene objetos compuestos por las siguientes propiedades: api_keys

El punto final de facturación del usuario (/billing/user)

Este Endpoint, el Endpoint de facturación de uso, le permite obtener información de facturación de 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 los demás puntos finales de facturación, puede especificar una cadena de consulta opcional como se muestra a continuación: months

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 realizó ningún uso durante el período de tiempo especificado, recibirá esta respuesta:

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

El objeto de respuesta contiene dos objetos, summary y api_keys y que pertenecen al usuario. Para obtener más información, consulte El objeto summary y La matriz api_keys arriba.

El punto final de facturación de la clave API (/billing/key)

Para obtener datos de uso de una clave API, puede utilizar el Endpoint de facturación de la clave API. Debe 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 los demás puntos finales de facturación, puede especificar una cadena de consulta opcional como se muestra a continuación: months

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 analizadas durante el período de tiempo especificado utilizando la clave API indicada en el encabezado, recibirán una respuesta como la siguiente: Authorization

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

El valor name es el nombre asignado a la clave API cuando se creó. Los otros valores, total_lines_linted y total_scans, especifican la cantidad de líneas que se analizaron en el período de tiempo especificado y la cantidad total de exploraciones que inició esta clave API en el período de tiempo especificado.

Referencia rápida de URL

Las URL importantes para usar con axe DevTools Linter SaaS son las siguientes:

Consulte Cómo obtener una clave API de axe DevTools Linter SaaS para obtener más información sobre los pasos necesarios para obtener una clave API.