Referenz zum Axe DevTools Linter REST-API

Mit Axe DevTools Linter können Sie Code auf Barrierefreiheitsprobleme überprüfen, indem Sie eine REST-API verwenden. Sie erstellen ein HTTP-Anfrageobjekt, das die zu prüfenden Quellzeilen enthält (im Body der Anfrage als JSON-Objekt), und der Server gibt ein Antwort-JSON-Objekt zurück, das auf mögliche Barrierefreiheitsprobleme hinweist, die der Server findet.

Der Server kann React (.js, .jsx, .ts und .tsx), Vue (.vue), Angular (.component.html), HTML (.html, .htm und .xhtml), LiquidJS (.liquid), HTL (.htl) und Markdown (.md und .markdown) Dateien überprüfen.

Die REST-Endpunkte

Der Server bietet sechs REST-Endpunkte. Der erste Endpunkt, (/lint-source), antwortet auf POST-Anfragen und prüft Ihren Code auf Barrierefreiheitsprobleme. Der zweite Endpunkt, (/status), antwortet auf GET-Anfragen und zeigt, ob der Server verfügbar ist, indem er mit einem 200-Statuscode anzeigt, dass der Server zuhört. Der dritte Endpunkt, (/healthcheck), antwortet auf GET-Anfragen, gibt an, ob der Server läuft, und liefert die Versionsnummer des laufenden Servers. Die verbleibenden drei Endpunkte ermöglichen es SaaS-Benutzern, Nutzungsinformationen für ihr gesamtes Unternehmen (/billing/enterprise), ihre Benutzer (/billing/user) und ihre API-Schlüssel (/billing/key) zu erhalten.

Die REST-Endpunkte sind wie folgt:

Der Lint-Endpunkt (/lint-source)

Der Lint-Endpunkt ist der primäre Serviceendpunkt. Sie können ihn verwenden, um Code an den Axe DevTools Linter zu senden, um auf Barrierefreiheitsprobleme zu prüfen. Er akzeptiert POST-Anfragen mit einem JSON-Body, der den zu prüfenden Code enthält.

Anfrage

Um diesen Endpunkt zu verwenden, erstellen Sie eine POST-Anfrage an den Lint-Endpunkt des Servers, wie im folgenden Beispiel gezeigt:

POST /lint-source

Sie müssen auch einen Content-Type-Header hinzufügen, um dem Server mitzuteilen, dass der Body der Anfrage ein JSON-Objekt enthält.

Content-Type: application/json

Wenn Sie Axe DevTools Linter SaaS verwenden, müssen Sie einen Authorization-Header mit Ihrem API-Schlüssel einschließen, wie unten gezeigt:

Authorization: <YOUR API KEY>

Weitere Informationen zum Erhalt eines API-Schlüssels finden Sie in Einen Axe DevTools Linter SaaS API-Schlüssel erhalten.

Der Body der Anfrage sollte den Code (in einem JSON-Objekt) enthalten, den Sie überprüfen möchten. Zum Beispiel wird mit dem folgenden JSON-Objekt ein Markdown-Beispiel geprüft:

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

Das obige Markdown-Beispiel enthält einen Barrierefreiheitsfehler: Die Überschriftsebenen haben eine Lücke zwischen der ersten Überschrift (Überschriftsebene 1) und der zweiten Überschrift (Überschriftsebene 3). Um die Serverantwort auf diesen Fehler zu sehen, lesen Sie den Abschnitt Antwort unten.

Das JSON-Anfrageobjekt

Die folgende Tabelle zeigt die Eigenschaften, die mit dem JSON-Anfrageobjekt verwendet werden:

Der source-String im JSON-Anfrageobjekt ist der Code, den Sie überprüfen lassen möchten. Sie müssen alle Anführungszeichen und Zeilenumbrüche escapen (durch Voranstellen eines Backslashes).

Der language-String kann einen der folgenden Werte annehmen:

Der Server verwendet die Eigenschaften filename und language, um herauszufinden, welcher Linter verwendet werden soll. Normalerweise verwendet Axe DevTools Linter die Dateierweiterung der Eigenschaft filename, um den Linter auszuwählen. Wenn Sie den zu verwendenden Linter stattdessen angeben möchten, können Sie die Eigenschaft language und die in der Tabelle oben angegebenen Werte verwenden. In diesem Fall müssen Sie trotzdem eine filename als erforderlichen Parameter angeben, aber language hat Vorrang vor der Dateierweiterung. Wenn Sie beispielsweise eine filename von „somefile.html“ und eine language von md angeben, wird der Markdown-Linter verwendet.

Antwort

Der Server antwortet mit einem Antwortcode von 200, unabhängig davon, ob Barrierefreiheitsfehler vorliegen oder nicht. Sie müssen das JSON im Antwortkörper prüfen, um festzustellen, ob Fehler vorliegen.

Wenn der Code keine Fehler aufweist, sieht das JSON-Antwortobjekt wie folgt aus:

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

Das folgende Beispiel zeigt das JSON-Antwortobjekt für eine Quelle, die einen Fehler hat (beachten Sie, dass errors ein Array von error-Objekten ist).

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

Das error-Objekt

Das errors-Array enthält error-Objekte, die die folgenden Eigenschaften aufweisen:

Das config-Objekt

Sie können eine config-Eigenschaft angeben, wenn Sie mehr Kontrolle über die Regeln haben möchten, die Axe DevTools Linter verwendet, um Ihren Quelltext auf Barrierefreiheitsfehler zu prüfen.

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

Das vorherige Beispiel zeigt, dass, obwohl der Quelltext einen Barrierefreiheitsfehler hat (ein fehlendes lang-Attribut im html-Element), keine Fehler zurückgegeben werden, weil diese Regel deaktiviert wurde.

Das global-components-Objekt

Das global-components-Objekt ordnet benutzerdefinierte Komponenten und deren Attribute bestehenden HTML-Elementen und Attributen zu. Für einführende Informationen zum Linting benutzerdefinierter Komponenten, siehe Linting benutzerdefinierter Komponenten.

Das folgende Beispiel zeigt eine vollständige Zuordnung einer benutzerdefinierten Komponente:

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

Das Beispiel zeigt die Zuordnung von der benutzerdefinierten Komponente custom-component zu html-element mit den Attributen custom-attribute-1 zu html-element-attribute1 und custom-attribute-2 zu <text>, was ein spezieller Attributwert ist, der custom-attribute-2 dem Textinhalt des Ausgabe-HTML-Elements zuordnet. Für weitere Informationen, siehe Der spezielle <text>-Wert.

Der spezielle aria-*-Wert gibt an, dass alle ARIA-Attribute auf dem benutzerdefinierten Element auf das Ausgabe-HTML-Element kopiert werden sollen. Siehe Verwendung von aria-* für weitere Informationen.

Die replace-Eigenschaft gibt an, ob custom-component aus dem Ausgabe-DOM-Baum entfernt werden soll, was Angular- und JavaScript-Benutzerelemente einschließen. Der Standardwert ist derselbe wie der Standard für die verwendete Technologie. D. h. true für Angular und HTML, false für JSX, TSX und Vue.

Wenn die benutzerdefinierte Komponente keine Attributzuordnung benötigt, können Sie dieses abgekürzte Format verwenden, das custom-component zu html-element zuordnet:

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

Die rules-Eigenschaft

Die rules-Eigenschaft bezieht sich auf ein LinterRuleset-Objekt, das es Ihnen ermöglicht, Regeln durch ihre Regel-ID zu aktivieren oder zu deaktivieren. Für weitere Informationen über die Barrierefreiheitsregeln, siehe Axe DevTools Linter Barrierefreiheitsregeln.

Zum Beispiel aktiviert die folgende Konfiguration die image-alt-Regel und deaktiviert die tabindex-Regel:

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

Für eine Liste von Regeln, gegen die der Server prüft, siehe Axe DevTools Linter-Barrierefreiheitsregeln

Die exclude-Eigenschaft

Die exclude-Eigenschaft kann verwendet werden, um Axe Linter anzuweisen, bestimmte Dateien beim Linting zu überspringen. Siehe Konfigurationsdatei in der Dokumentation für Axe DevTools Linter Connector für weitere Informationen.

Die tags-Eigenschaft

Die tags-Eigenschaft ist ein Array von Strings oder Tags. Jedes Tag ist an eine oder mehrere Barrierefreiheitsregeln gekoppelt, sodass durch die Angabe mehrerer Tags hier viele verschiedene Barrierefreiheitsregeln aktiviert werden können (und alle Regeln deaktiviert werden, die nicht mit den angegebenen Tags versehen sind). Die Tags entsprechen typischerweise verschiedenen Barrierefreiheitsstandards, und jede Regel kann Mitglied vieler verschiedener Tags sein.

Der Status-Endpunkt (/status)

Der Health-Check-Endpunkt (/healthcheck)

Um zu prüfen, ob der Server läuft, und um seine Versionsnummer zurückzugeben, senden Sie eine GET-Anfrage an den Health-Check-Endpunkt. Ein Beispiel einer Anfrage wird unten gezeigt:

GET /healthcheck

Wenn der Server läuft, antwortet er mit der Versionsnummer des Servers, wie im unten gezeigten Beispiel:

{
  "version": "4.10.3"
}

Der Enterprise-Billing-Endpunkt (/billing/enterprise)

Der Enterprise-Billing-Endpunkt ermöglicht es Ihnen, Gesamtverwendungsinformationen für Ihr Unternehmen zu erhalten sowie die Nutzung aufgeschlüsselt nach einzelnen API-Schlüsseln. Der Endpunkt antwortet auf eine GET-Anfrage und erfordert, dass Sie ein Jahr und einen Monat angeben (hier Mai 2022), wie unten gezeigt:

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

Die Anfrage erfordert einen authorization-Header mit Ihrem API-Schlüssel. Siehe Einen API-Schlüssel erhalten für weitere Informationen.

Standardmäßig gibt der Server einen Monat an Daten zurück, aber Sie können den optionalen months=<number-of-months-data>-Abfrageparameter verwenden, um mehr anzugeben. Der months-Parameter kann im Bereich von 1 bis 12 (inklusive) liegen. Das unten gezeigte Beispiel zeigt, wie man drei Monate an Daten erhält, beginnend mit Mai 2022:

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

Antwort

Der SaaS-Linter-Server antwortet mit einem JSON-Objekt, das zwei Objekte enthält. Das erste ist ein summary-Objekt, und das zweite, api_keys, ist eine Sammlung von Objekten, die Informationen über die Nutzung des Linter-Dienstes durch jeden API-Schlüssel enthalten.

Ein Beispiel für ein Antwortobjekt wird unten gezeigt:

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

Wenn es keine Daten für den angegebenen Zeitraum gibt, sieht die Antwort wie folgt aus:

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

Das summary-Objekt

Das summary-Objekt gibt Ihnen Informationen über die Gesamtanzahl der gelinteten Zeilen und wie viele Scans von Benutzern innerhalb des Unternehmens initiiert wurden.

Das api_keys-Array

Das api_keys-Array enthält Objekte, die aus den folgenden Eigenschaften bestehen:

Die Benutzerabrechnungs-Schnittstelle (/billing/user)

Diese Schnittstelle, die Nutzungsabrechnungs-Schnittstelle, ermöglicht es Ihnen, Abrechnungsinformationen für einen Benutzer für alle API-Schlüssel zu erhalten, die zum Zugriff auf den SaaS-Server verwendet wurden. Standardmäßig werden die Daten eines Monats zurückgegeben.

Das folgende Beispiel zeigt eine Anfrage für Mai 2022 für den Benutzer, der durch den bereitgestellten API-Schlüssel (im authorization Header) dargestellt wird:

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

Wie bei den anderen Abrechnungs-Schnittstellen können Sie eine optionale months-Abfragezeichenfolge wie unten gezeigt angeben:

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

Das folgende Beispiel zeigt ein Antwortobjekt:

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

Wenn der Benutzer für den angegebenen Zeitraum keine Nutzung hatte, würden Sie diese Antwort erhalten:

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

Das Antwortobjekt enthält zwei Objekte, summary und api_keys, die zum Benutzer gehören. Für weitere Informationen siehe Das summary-Objekt und Das api_keys-Array oben.

Die API-Schlüsselabrechnungs-Schnittstelle (/billing/key)

Um Nutzungsdaten für einen API-Schlüssel zu erhalten, können Sie die API-Schlüsselabrechnungs-Schnittstelle verwenden. Sie müssen das Jahr und den Monat wie unten gezeigt angeben:

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

Wie bei den anderen Abrechnungs-Schnittstellen können Sie eine optionale months-Abfragezeichenfolge wie unten gezeigt angeben:

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

Unten wird ein Beispiel-Antwortobjekt angezeigt:

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

Wenn während des angegebenen Zeitraums keine Zeilen unter Verwendung des im Authorization Header angegebenen API-Schlüssels geprüft wurden, würden Sie eine Antwort wie die folgende erhalten:

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

Der name-Wert ist der Name, der dem API-Schlüssel bei der Erstellung zugewiesen wurde. Die anderen Werte, total_lines_linted und total_scans, geben die Anzahl der Zeilen an, die im angegebenen Zeitraum geprüft wurden, und die Gesamtzahl der Scans, die mit diesem API-Schlüssel im angegebenen Zeitraum initiiert wurden.

Schnellreferenz für URLs

Wichtige URLs für die Verwendung mit Axe DevTools Linter SaaS sind wie folgt:

Weitere Informationen zu den Schritten zum Erhalt eines API-Schlüssels finden Sie unter Erhalt eines Axe DevTools Linter SaaS-API-Schlüssels.