Référence de l'API REST de l'axe DevTools Linter

Axe DevTools Linter vous permet de vérifier le code pour les 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 qui indique les problèmes d'accessibilité détectés 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) 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 POST requêtes et vérifie votre code pour détecter les problèmes d'accessibilité. Le deuxième point de terminaison, (/status), répond aux GET requêtes 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 GET requêtes, 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 points de terminaison restants 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 Lint (/lint-source)

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

Demande

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

POST /lint-source

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

Content-Type: application/json

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

Authorization: <YOUR API KEY>

Vous pouvez en savoir plus sur l'obtention d'une clé API dans Obtention d'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'exemple Markdown ci-dessus présente une erreur d'accessibilité : les niveaux de titre présentent 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 dans l’objet JSON de requête est le code que vous souhaitez vérifier. source You need to escape all quotes and newlines (precede with a backslash).

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

Le serveur utilise les propriétés filename et language pour déterminer quel linter utiliser. Habituellement, axe DevTools Linter utilisera l'extension de fichier sur la propriété filename pour choisir le linter. Si vous souhaitez spécifier le linter à utiliser à la place, vous pouvez utiliser la propriété language et les valeurs spécifiées dans le tableau ci-dessus. Dans ce cas, vous devez toujours spécifier un filename comme paramètre obligatoire, mais language a priorité 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

The server responds with a response code of 200 whether or not there are any accessibility errors. Vous devez examiner le JSON dans le corps de la réponse pour voir s'il y a des erreurs.

If the code has no errors, the JSON response object is as follows:

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

L'exemple suivant montre l'objet JSON de réponse pour la source qui comporte 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' error Objet

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

L' config Objet

Vous pouvez spécifier une propriété si vous souhaitez plus de contrôle sur les règles qu'axe DevTools Linter utilise pour vérifier votre source pour les erreurs d'accessibilité. config

{
  "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 comporte une erreur d'accessibilité (un attribut manquant sur l'élément), aucune erreur ne sera renvoyée car cette règle a été désactivée. lang html

L' global-components Objet

L'objet mappe les composants personnalisés et leurs attributs aux éléments et attributs HTML existants. global-components Pour obtenir des informations introductives sur l'analyse statique des composants personnalisés, consultez Linting Custom Components.

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

{
  "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 la correspondance du composant personnalisé custom-component vers html-element avec des attributs custom-attribute-1 correspondant à html-element-attribute1 et custom-attribute-2 correspondant à <text>, qui est une valeur d'attribut spéciale correspondant custom-attribute-2 au contenu textuel de l'élément HTML de sortie. Pour plus d'informations, voir La valeur spéciale <text>.

Le spécial aria-* value indicates that all ARIA attributes on the custom element should be copied to the output HTML element. See Using aria-* pour plus d'informations.

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

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

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

La rules Propriété

La propriété fait référence à un objet qui vous permet d'activer ou de désactiver des règles en fonction de leur ID de règle. rules LinterRuleset Pour plus d'informations sur les règles d'accessibilité, consultez axe DevTools Linter Accessibility Rules.

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

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

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

La exclude Propriété

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

La tags Propriété

La propriété est un tableau de chaînes ou de balises. tags ** Chaque balise est associée à une ou plusieurs règles d'accessibilité. Ainsi, en spécifiant plusieurs balises ici, vous pouvez activer de nombreuses règles d'accessibilité différentes (et désactiver toutes les règles qui ne sont pas balisées avec les balises spécifiées). Les balises correspondent généralement à différentes normes d’accessibilité, et chaque règle peut être membre de plusieurs balises différentes.

Le point de terminaison d'état (/status)

Le point de terminaison du contrôle de santé (/healthcheck)

Pour vérifier si le serveur est en cours d'exécution et renvoyer son numéro de version, envoyez une GET requête au point de terminaison du contrôle de santé. Un exemple de demande est présenté 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 indiqué dans l'exemple ci-dessous :

{
  "version": "4.10.3"
}

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

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

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

La demande nécessite un en-tête avec votre clé API. authorization Consultez 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 facultative pour en spécifier davantage. months=<number-of-months-data> Le paramètre peut varier de 1 à 12 (inclus). months L'exemple ci-dessous illustre l'obtention de trois mois de données commençant par 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 contenant deux objets. Le premier est un summary objet, et le second, api_keys, est une collection d'objets qui contiennent des informations sur l'utilisation de chaque clé API du service linter.

Un exemple d’objet de réponse est présenté 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
  }]
}

S'il n'y a pas de données pour la période spécifiée, la réponse ressemblera à ceci :

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

L' summary Objet

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

Le api_keys tableau

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

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 des informations de facturation pour un utilisateur pour toutes les clés API utilisées pour accéder au serveur SaaS. La valeur par défaut est que les données d'un mois sont renvoyées.

L'exemple suivant montre une demande 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 facultative comme indiqué ci-dessous : months

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

Ce qui suit montre un exemple d’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 pas utilisé le service pendant 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 appartenant à l'utilisateur, summary et api_keys . Pour plus d'informations, voir L'objet summary et Le tableau api_keys ci-dessus.

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

Pour obtenir des données d’utilisation pour une clé API, vous pouvez utiliser le point de terminaison de facturation de la clé API. Vous devez spécifier l'année et le mois comme indiqué 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 facultative comme indiqué ci-dessous : months

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

Un exemple d’objet de réponse est présenté ci-dessous :

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

S'il n'y a eu aucune ligne analysée pendant la période spécifiée à l'aide de la clé API spécifiée dans l'en-tête, vous recevrez une réponse telle que la suivante : Authorization

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

La name valeur 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 au cours de la période spécifiée et le nombre total d'analyses qui ont été lancées par cette clé API au cours de la période spécifiée.

Référence rapide de l'URL

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

Consultez Obtention d'une clé API axe DevTools Linter SaaS pour plus d'informations sur les étapes requises pour obtenir une clé API.