Die axe DevTools Linter REST API-Referenz

Mit axe DevTools Linter können Sie Code mithilfe einer REST-API auf Zugänglichkeitsprobleme überprüfen. Sie erstellen ein HTTP-Anforderungsobjekt, das die Quellzeilen enthält, die Sie überprüfen möchten (im Körper der Anforderung als JSON-Objekt), und der Server gibt ein JSON-Antwortobjekt zurück, das alle vom Server gefundenen Zugänglichkeitsprobleme angibt.

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

Die REST-Endpunkte

Der Server stellt sechs REST-Endpunkte bereit. Der erste Endpunkt (/lint-source) antwortet auf POST Anfragen und überprüft Ihren Code auf Zugänglichkeitsprobleme. Der zweite Endpunkt (/status) antwortet auf GET Anfragen und zeigt mit einem 200-Antwortcode an, ob der Server verfügbar ist. Der dritte Endpunkt (/healthcheck) antwortet auf GET Anfragen, zeigt an, ob der Server läuft, und gibt die Versionsnummer des laufenden Servers zurück. Über die verbleibenden drei Endpunkte können Benutzer der SaaS-Edition Nutzungsinformationen für ihr gesamtes Unternehmen (/billing/enterprise), ihre Benutzer (/billing/user) und ihre API-Schlüssel (/billing/key) abrufen.

Die REST-Endpunkte sind wie folgt:

Der Lint-Endpunkt (/lint-source)

Der Lint-Endpunkt ist der primäre Service-Endpunkt. Sie können damit Code an axe DevTools Linter senden, um nach Zugänglichkeitsproblemen zu suchen. Es akzeptiert POST Anfragen mit einem JSON-Text, 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 einfügen, um dem Server mitzuteilen, dass der Anforderungstext 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 hinzufügen, wie unten gezeigt:

Authorization: <YOUR API KEY>

Weitere Informationen zum Abrufen eines API-Schlüssels finden Sie unter Abrufen eines axe DevTools Linter SaaS-API-Schlüssels.

Der Text der Anfrage sollte den Code (innerhalb eines JSON-Objekts) enthalten, den Sie überprüfen möchten. Beispielsweise wird mit dem folgenden JSON-Objekt ein Markdown-Beispiel überprüft:

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

Das obige Markdown-Beispiel weist einen Zugänglichkeitsfehler auf: Die Überschriftenebenen weisen eine Lücke zwischen der ersten Überschrift (Überschriftebene 1) und der zweiten Überschrift (Überschriftebene 3) auf. Die Antwort des Servers auf diesen Fehler finden Sie weiter unten im Abschnitt Antwort .

Das JSON-Anforderungsobjekt

Die folgende Tabelle zeigt die mit dem JSON-Anforderungsobjekt verwendeten Eigenschaften:

Die Zeichenfolge source im JSON-Anforderungsobjekt ist der Code, den Sie überprüfen möchten. Sie müssen alle Anführungszeichen und Zeilenumbrüche maskieren (mit einem Backslash voranstellen).

Die Zeichenfolge language 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 filename -Eigenschaft, um den Linter auszuwählen. Wenn Sie stattdessen den zu verwendenden Linter angeben möchten, können Sie die language -Eigenschaft und die in der obigen Tabelle angegebenen Werte verwenden. In diesem Fall müssen Sie dennoch einen filename als erforderlichen Parameter angeben, aber language hat Vorrang vor der Dateinamenerweiterung. Wenn Sie beispielsweise ein filename von „somefile.html“ und ein language von md angeben, verwendet der Server den Markdown-Linter.

Antwort

Der Server antwortet mit einem Antwortcode von 200, unabhängig davon, ob Zugänglichkeitsfehler vorliegen oder nicht. Sie müssen das JSON im Textkörper der Antwort untersuchen, um festzustellen, ob Fehler vorliegen.

Wenn der Code fehlerfrei ist, sieht das JSON-Antwortobjekt wie folgt aus:

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

Das folgende Beispiel zeigt das JSON-Antwortobjekt für eine Quelle, die einen Fehler aufweist (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 mit den folgenden Eigenschaften:

Das config Objekt

Sie können eine config Eigenschaft angeben, wenn Sie mehr Kontrolle über die Regeln wünschen, die axe DevTools Linter verwendet, um Ihre Quelle auf Zugänglichkeitsfehler zu überprüfen.

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

Das vorherige Beispiel zeigt, dass, obwohl die Quelle einen Zugänglichkeitsfehler aufweist (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 vorhandenen HTML-Elementen und -Attributen zu. Einführende Informationen zum Linting benutzerdefinierter Komponenten finden Sie unter Linting benutzerdefinierter Komponenten.

Das folgende Beispiel zeigt eine vollständige benutzerdefinierte Komponentenzuordnung:

{
  "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 zugeordnet zu html-element-attribute1 und custom-attribute-2 zugeordnet zu <text>, einem speziellen Attributwert, der dem Textinhalt des ausgegebenen HTML-Elements zugeordnet wird custom-attribute-2 . Weitere Informationen finden Sie unter Der spezielle <text>-Wert.

Das spezielle aria-* value indicates that all ARIA attributes on the custom element should be copied to the output HTML element. See Using aria-* für weitere Informationen.

Die replace Eigenschaft gibt an, ob custom-component aus dem Ausgabe-DOM-Baum entfernt werden soll, der benutzerdefinierte Elemente von Angular und JavaScript enthält. Der Standardwert entspricht dem Standardwert der verwendeten Technologie. D. h. true für Angular und HTML, false für JSX, TSX und Vue.

Wenn für die benutzerdefinierte Komponente keine Attributzuordnung erforderlich ist, können Sie dieses verkürzte Format verwenden, das custom-component auf html-element abbildet:

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

Die rules Eigenschaft

Die rules Eigenschaft verweist auf ein LinterRuleset Objekt, das es Ihnen ermöglicht, Regeln anhand ihrer Regel-ID zu aktivieren oder zu deaktivieren. Weitere Informationen zu den Barrierefreiheitsregeln finden Sie unter axe DevTools Linter Accessibility Rules.

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

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

Eine Liste der Regeln, die der Server prüft, finden Sie unter [axe DevTools Linter Accessibility Rules].(axe-linter-rules)

Die exclude Eigenschaft

Mit der exclude -Eigenschaft kann der axe linter angewiesen werden, beim Linting bestimmte Dateien zu überspringen. Weitere Informationen finden Sie in der Konfigurationsdatei in der Dokumentation zum axe DevTools Linter Connector.

Die tags Eigenschaft

Die tags Eigenschaft ist ein Array von Zeichenfolgen oder Tags. Jedes Tag ist mit einer oder mehreren Zugänglichkeitsregeln verknüpft. Wenn Sie hier mehrere Tags angeben, können Sie daher viele verschiedene Zugänglichkeitsregeln einschalten (und alle Regeln ausschalten, die nicht mit den angegebenen Tags versehen sind). Die Tags entsprechen normalerweise unterschiedlichen Zugänglichkeitsstandards und jede Regel kann Mitglied vieler verschiedener Tags sein.

Der Status-Endpunkt (/status)

Der Integritätsprüfungsendpunkt (/healthcheck)

Um zu überprüfen, ob der Server ausgeführt wird, und seine Versionsnummer zurückzugeben, senden Sie eine GET Anfrage an den Integritätsprüfungsendpunkt. Nachfolgend sehen Sie eine Beispielanforderung:

GET /healthcheck

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

{
  "version": "4.10.3"
}

Der Enterprise-Abrechnungsendpunkt (/billing/enterprise)

Über den Enterprise-Abrechnungsendpunkt können Sie Gesamtnutzungsinformationen für Ihr Unternehmen und die Nutzung aufgeschlüsselt nach einzelnen API-Schlüsseln abrufen. Der Endpunkt antwortet auf eine GET Anfrage und erfordert die Angabe eines Jahres und Monats (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. Weitere Informationen finden Sie unter Abrufen eines API-Schlüssels .

Standardmäßig gibt der Server Daten für einen Monat zurück, aber Sie können mit der optionalen Abfragezeichenfolge months=<number-of-months-data> mehr angeben. Der Parameter months kann zwischen 1 und 12 (einschließlich) liegen. Das folgende Beispiel zeigt die Erfassung von Daten für drei Monate ab 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 zur Verwendung des Linter-Dienstes durch jeden API-Schlüssel enthalten.

Unten wird ein Beispiel für ein Antwortobjekt angezeigt:

{
  "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 für den angegebenen Zeitraum keine Daten vorliegen, würde die Antwort folgendermaßen aussehen:

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

Das summary Objekt

Das summary Objekt gibt Ihnen Auskunft über die Gesamtzahl der linteten Zeilen und darüber, wie viele Scans von Benutzern im Unternehmen initiiert wurden.

Das api_keys Array

Das api_keys Array enthält Objekte mit den folgenden Eigenschaften:

Der Benutzer-Billing-Endpoint (/billing/user)

Über diesen Endpunkt, den Endpunkt für die Nutzungsabrechnung, können Sie Abrechnungsinformationen für einen Benutzer für alle API-Schlüssel abrufen, die für den Zugriff auf den SaaS-Server verwendet werden. 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 Abrechnungsendpunkten können Sie eine optionale months Abfragezeichenfolge angeben, wie unten gezeigt:

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

Nachfolgend sehen Sie ein Beispiel für 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 im angegebenen Zeitraum keine Nutzung vorgenommen hat, erhalten Sie diese Antwort:

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

Das Antwortobjekt enthält zwei Objekte, summary die dem Benutzer gehören. api_keys Weitere Informationen finden Sie oben unter Das summary-Objekt und Das api_keys-Array .

Der API-Schlüssel-Abrechnungsendpunkt (/billing/key)

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

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

Wie bei den anderen Abrechnungsendpunkten können Sie eine optionale months Abfragezeichenfolge angeben, wie unten gezeigt:

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

Unten wird ein Beispiel für ein Antwortobjekt angezeigt:

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

Wenn während des angegebenen Zeitraums keine Zeilen mit dem im Authorization Header angegebenen API-Schlüssel gelintet wurden, erhalten Sie eine Antwort wie die folgende:

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

Der name Wert ist der Name, der dem API-Schlüssel bei seiner 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 im angegebenen Zeitraum von diesem API-Schlüssel initiiert wurden.

URL-Kurzreferenz

Wichtige URLs zur Verwendung mit axe DevTools Linter SaaS lauten wie folgt:

Weitere Informationen zu den erforderlichen Schritten zum Abrufen eines API-Schlüssels finden Sie unter Abrufen eines axe DevTools Linter SaaS-API-Schlüssels .