Référence de l'API REST de l'interpréteur Axe DevTools

Axe DevTools Linter vous permet de vérifier le code pour des problèmes d'accessibilité à l'aide d'une API REST. Vous créez un objet de requête HTTP qui contient les lignes de code que vous souhaitez vérifier (dans le corps de la requête en tant qu'objet JSON), et le serveur renvoie un objet JSON de réponse indiquant tout problème d'accessibilité détecté par le serveur.

Le serveur peut vérifier les fichiers React (.js, .jsx, .ts, et .tsx), Vue (.vue), Angular (.component.html), HTML (.html, .htm, et .xhtml), LiquidJS (.liquid), HTL (.htl), et Markdown (.md et .markdown).

Les points de terminaison REST

Le serveur fournit six points de terminaison REST. Le premier point de terminaison, (/lint-source), répond aux requêtes POST et vérifie si votre code présente des problèmes d'accessibilité. Le deuxième point de terminaison, (/status), répond aux requêtes GET et indique si le serveur est disponible avec un code de réponse 200 indiquant que le serveur est à l'écoute. Le troisième point de terminaison, (/healthcheck), répond aux requêtes GET, indique si le serveur est en cours d'exécution et renvoie le numéro de version du serveur en cours d'exécution. Les trois autres points de terminaison permettent aux utilisateurs de l'édition SaaS d'obtenir des informations d'utilisation pour leur entreprise dans son ensemble (/billing/enterprise), leurs utilisateurs (/billing/user), et leurs clés API (/billing/key).

Les points de terminaison REST sont les suivants :

Le point de terminaison de lint (/lint-source)

Le point de terminaison de lint est le principal point de service. Vous pouvez l'utiliser pour envoyer du code à l'Axe DevTools Linter afin de vérifier les problèmes d'accessibilité. Il accepte les requêtes POST avec un corps JSON contenant le code à vérifier.

Requête

Pour utiliser ce point de terminaison, vous créez une requête POST vers le point de terminaison lint du serveur, comme indiqué dans l'exemple ci-dessous :

POST /lint-source

Vous devez également inclure un en-tête Content-Type pour indiquer au serveur que le corps de la requête contient un objet JSON.

Content-Type: application/json

Si vous utilisez Axe DevTools Linter SaaS, vous devrez inclure un en-tête Authorization avec votre clé API, comme indiqué ci-dessous :

Authorization: <YOUR API KEY>

Vous pouvez en savoir plus sur l'obtention d'une clé API dans Obtenir une clé API Axe DevTools Linter SaaS.

Le corps de la requête doit contenir le code (à l'intérieur d'un objet JSON) que vous souhaitez vérifier. Par exemple, l'objet JSON suivant vérifie un échantillon de markdown :

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

L'échantillon Markdown ci-dessus présente une erreur d'accessibilité : les niveaux de titres ont un écart entre le premier titre (niveau de titre 1) et le deuxième titre (niveau de titre 3). Pour voir la réponse du serveur à cette erreur, consultez la section Réponse ci-dessous.

L'objet de requête JSON

Le tableau suivant montre les propriétés utilisées avec l'objet de requête JSON :

La chaîne source dans l'objet JSON de la requête est le code que vous souhaitez vérifier. Vous devez échapper tous les guillemets et les nouvelles lignes (précéder d'un antislash).

La chaîne language peut prendre l'une des valeurs suivantes :

Le serveur utilise les propriétés filename et language pour déterminer quel linter utiliser. En général, Axe DevTools Linter utilise l'extension de fichier de la propriété filename pour choisir le linter. Si vous souhaitez spécifier le linter à utiliser, vous pouvez utiliser la propriété language et les valeurs indiquées dans le tableau ci-dessus. Dans ce cas, vous devez toujours spécifier un filename comme paramètre obligatoire, mais language prend le pas sur l'extension du nom de fichier. Par exemple, si vous spécifiez un filename de "somefile.html" et un language de md, le serveur utilisera le linter Markdown.

Réponse

Le serveur répond avec un code de réponse 200, qu'il y ait ou non des erreurs d'accessibilité. Vous devez examiner le JSON dans le corps de la réponse pour voir s'il y a des erreurs.

Si le code n'a pas d'erreurs, l'objet de réponse JSON est le suivant :

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

L'exemple suivant montre l'objet JSON de réponse pour une source qui a une erreur (notez que errors est un tableau d'objets 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
      }
    ]
  }
}

L'objet error

Le tableau errors contient des objets error, qui ont les propriétés suivantes :

L'objet config

Vous pouvez spécifier une propriété config si vous souhaitez un meilleur contrôle sur les règles qu'Axe DevTools Linter utilise pour vérifier votre source à la recherche d'erreurs d'accessibilité.

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

L'exemple précédent montre que, bien que la source ait une erreur d'accessibilité (un attribut lang manquant sur l'élément html), aucune erreur ne sera retournée car cette règle a été désactivée.

L'objet global-components

L'objet global-components fait correspondre les composants personnalisés et leurs attributs à des éléments et attributs HTML existants. Pour des informations introductives sur le linting des composants personnalisés, consultez Linting des composants personnalisés.

L'exemple suivant montre un mappage complet de composant personnalisé :

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

L'exemple montre le mappage du composant personnalisé custom-component à html-element avec des attributs custom-attribute-1 mappés à html-element-attribute1 et custom-attribute-2 mappés à <text>, qui est une valeur d'attribut spéciale qui mappe custom-attribute-2 au contenu texte de l'élément HTML de sortie. Pour plus d'informations, voir La valeur spéciale <text>.

La valeur spéciale aria-* indique que tous les attributs ARIA sur l'élément personnalisé doivent être copiés sur l'élément HTML de sortie. Voir Utilisation de aria-* pour plus d'informations.

La propriété replace indique si custom-component doit être supprimé de l'arbre DOM de sortie, ce qui inclut les éléments personnalisés Angular et JavaScript. La valeur par défaut est la même que pour la technologie utilisée. C'est-à-dire true pour Angular et HTML, false pour JSX, TSX et Vue.

Si le composant personnalisé n'exige pas de mappage d'attributs, vous pouvez utiliser ce format abrégé qui mappe custom-component à html-element :

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

La propriété rules

La propriété rules fait référence à un objet LinterRuleset, qui vous permet d'activer ou de désactiver des règles par leur ID. Pour plus d'informations sur les règles d'accessibilité, voir Règles d'accessibilité d'Axe DevTools Linter.

Par exemple, la configuration suivante active la règle image-alt et désactive la règle tabindex :

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

Pour une liste des règles que le serveur vérifie, voir Règles d'accessibilité de l'Axe DevTools Linter

La propriété exclude

La propriété exclude peut être utilisée pour indiquer à Axe Linter d'ignorer certains fichiers lors de l'analyse. Voir Fichier de configuration dans la documentation pour Axe DevTools Linter Connector pour plus d'informations.

La propriété tags

La propriété tags est un tableau de chaînes ou tags. Chaque tag est associé à une ou plusieurs règles d'accessibilité, ce qui permet, en spécifiant plusieurs tags ici, d'activer de nombreuses règles d'accessibilité différentes (et de désactiver toute règle qui n'est pas étiquetée avec les tags spécifiés). Les tags correspondent généralement à différents standards d'accessibilité, et chaque règle peut être membre de nombreux tags différents.

Le point de terminaison de statut (/status)

Le point de terminaison de vérification de la santé (/healthcheck)

Pour vérifier si le serveur est en cours d'exécution et retourner son numéro de version, envoyez une requête GET au point de terminaison de vérification de la santé. Un exemple de requête est montré ci-dessous :

GET /healthcheck

Si le serveur est en cours d'exécution, il répondra avec le numéro de version du serveur, comme montré dans l'exemple ci-dessous :

{
  "version": "4.10.3"
}

Le point de terminaison de facturation d'entreprise (/billing/enterprise)

Le point de terminaison de facturation d'entreprise vous permet d'obtenir des informations sur l'utilisation totale de votre entreprise et l'utilisation détaillée par clés API individuelles. Le point de terminaison répond à une requête GET et nécessite de spécifier une année et un mois (ici, mai 2022), comme montré ci-dessous :

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

La requête nécessite un en-tête authorization avec votre clé API. Voir Obtention d'une clé API pour plus d'informations.

Par défaut, le serveur renvoie un mois de données, mais vous pouvez utiliser la chaîne de requête months=<number-of-months-data> optionnelle pour en spécifier plus. Le paramètre months peut varier de 1 à 12 (inclus). L'exemple ci-dessous montre comment obtenir trois mois de données à partir de mai 2022 :

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

Réponse

Le serveur linter SaaS répond avec un objet JSON qui contient deux objets. Le premier est un objet summary, et le second, api_keys, est une collection d'objets contenant des informations sur l'utilisation du service linter pour chaque clé API.

Un exemple d'objet réponse est montré ci-dessous :

{
  "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 aucune donnée n'est disponible pour la période spécifiée, la réponse ressemblera à ceci :

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

L'objet summary

L'objet summary vous donne des informations sur le nombre total de lignes analysées et le nombre de scans initiés par les utilisateurs au sein de l'entreprise.

Le tableau api_keys

Le tableau api_keys contient des objets composés des propriétés suivantes :

Le point de terminaison de facturation utilisateur (/billing/user)

Ce point de terminaison, le point de terminaison de facturation d'utilisation, vous permet d'obtenir les informations de facturation pour un utilisateur pour toutes les clés API utilisées pour accéder au serveur SaaS. Par défaut, les données d'un mois sont retournées.

L'exemple suivant montre une requête pour mai 2022 pour l'utilisateur représenté par la clé API fournie (dans l'en-tête authorization) :

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

Comme les autres points de terminaison de facturation, vous pouvez spécifier une chaîne de requête months optionnelle comme montré ci-dessous :

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

L'exemple suivant montre un objet de réponse :

{
  "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 l'utilisateur n'a eu aucune utilisation pour la période spécifiée, vous recevrez cette réponse :

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

L'objet de réponse contient deux objets, summary et api_keys appartenant à l'utilisateur. Pour plus d'informations, voir L'Objet summary et Le Tableau api_keys ci-dessus.

Le point de terminaison de facturation des clés API (/billing/key)

Pour obtenir les données d'utilisation d'une clé API, vous pouvez utiliser le point de terminaison de facturation des clés API. Vous devez spécifier l'année et le mois comme montré ci-dessous :

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

Comme les autres points de terminaison de facturation, vous pouvez spécifier une chaîne de requête months optionnelle comme montré ci-dessous :

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

Un exemple d'objet de réponse est montré ci-dessous :

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

S'il n'y avait pas de lignes lintées pendant la période spécifiée en utilisant la clé API spécifiée dans l'en-tête Authorization, vous recevrez une réponse telle que la suivante :

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

La valeur name est le nom attribué à la clé API lors de sa création. Les autres valeurs, total_lines_linted et total_scans, spécifient le nombre de lignes qui ont été analysées pendant la période spécifiée et le nombre total de scans qui ont été initiés par cette clé API pendant la période spécifiée.

Référence rapide des URL

Les URL importantes à utiliser avec Axe DevTools Linter SaaS sont les suivantes :

Voir Obtenir une clé API Axe DevTools Linter SaaS pour plus d'informations sur les étapes nécessaires pour obtenir une clé API.