De Axe DevTools Linter REST API-referentie

Met Axe DevTools Linter kunt u code controleren op toegankelijkheidsproblemen via een REST API. U maakt een HTTP-verzoekobject dat de bronregels bevat die u wilt laten controleren (in de body van het verzoek als een JSON-object), en de server retourneert een JSON-reactieobject dat aangeeft welke toegankelijkheidsproblemen de server vindt.

De server kan React (.js, .jsx, .ts en .tsx), Vue (.vue), Angular (.component.html), HTML (.html, .htm en .xhtml), LiquidJS (.liquid) en Markdown (.md en .markdown) bestanden controleren.

De REST-eindpunten

De server biedt zes REST-eindpunten. Het eerste eindpunt, (/lint-source), reageert op POST verzoeken en controleert uw code op toegankelijkheidsproblemen. Het tweede eindpunt, (/status), reageert op GET verzoeken en toont of de server beschikbaar is met een 200-responscode die aangeeft dat de server klaarstaat. Het derde eindpunt, (/healthcheck), reageert op GET verzoeken, geeft aan of de server draait en retourneert het versienummer van de draaiende server. De overige drie eindpunten stellen gebruikers van de SaaS-editie in staat om gebruiksinformatie voor hun gehele onderneming te verkrijgen (/billing/enterprise), hun gebruikers (/billing/user), en hun API-sleutels (/billing/key).

De REST-eindpunten zijn als volgt:

Het Lint-eindpunt (/lint-source)

Het lint-eindpunt is het primaire service-eindpunt. U kunt het gebruiken om code naar Axe DevTools Linter te sturen om te controleren op toegankelijkheidsproblemen. Het accepteert POST verzoeken met een JSON-body die de te controleren code bevat.

Verzoek

Om dit eindpunt te gebruiken, maakt u een POST verzoek aan het lint-eindpunt van de server, zoals in het onderstaande voorbeeld:

POST /lint-source

U moet ook een Content-Type header opnemen om de server te vertellen dat de body van het verzoek een JSON-object bevat.

Content-Type: application/json

Als u Axe DevTools Linter SaaS gebruikt, moet u een Authorization header opnemen met uw API-sleutel, zoals hieronder getoond:

Authorization: <YOUR API KEY>

U kunt meer leren over het verkrijgen van een API-sleutel in Het verkrijgen van een Axe DevTools Linter SaaS API-sleutel.

De body van het verzoek moet de code bevatten (in een JSON-object) die u wilt controleren. Bijvoorbeeld, het volgende JSON-object controleert een markdown-sample:

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

Het bovenstaande Markdown-sample heeft een toegankelijkheidsfout: er is een verschil in de kopniveau's tussen de eerste kop (kopniveau 1) en de tweede kop (kopniveau 3). Om de reactie van de server op deze fout te zien, zie de Reactie sectie hieronder.

Het JSON-verzoekobject

De volgende tabel toont de eigenschappen die gebruikt worden met het JSON-verzoekobject:

De source string in het verzoek JSON-object is de code die u wilt controleren. U moet alle aanhalingen en nieuwe regels escapen (voorafgaan met een backslash).

De language string kan een van de volgende waarden aannemen:

De server gebruikt de filename en language eigenschappen om te bepalen welke linter te gebruiken. Meestal zal Axe DevTools Linter de bestandsextensie op het filename eigenschap gebruiken om de linter te kiezen. Als u liever zelf de linter specificeert, kunt u de language eigenschap en de waarden gespecificeerd in de bovenstaande tabel gebruiken. In dit geval moet u nog steeds een filename als vereiste parameter opgeven, maar language heeft voorrang op de extensie van de bestandsnaam. Als u bijvoorbeeld een filename van „somefile.html“ en een language van md, zal de server de Markdown linter gebruiken.

Antwoord

De server reageert met een antwoordcode van 200 ongeacht of er toegankelijkheidsfouten zijn. U moet de JSON in de body van het antwoord onderzoeken om te zien of er fouten zijn.

Als de code geen fouten heeft, ziet het JSON-antwoordsobject er als volgt uit:

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

Het volgende voorbeeld toont het JSON-antwoordsobject voor code die een fout heeft (merk op dat errors een array van error objecten is).

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

Het error Object

De errors array bevat error objecten, die de volgende eigenschappen hebben:

Het config Object

Je kunt een config eigenschap specificeren als je meer controle wilt over de regels die Axe DevTools Linter gebruikt om je bron te controleren op toegankelijkheidsfouten.

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

Het vorige voorbeeld laat zien dat, hoewel de bron een toegankelijkheidsfout heeft (een ontbrekend lang attribuut op het html element), er geen fouten worden geretourneerd omdat die regel is uitgeschakeld.

Het global-components Object

Het global-components object kaart aangepaste componenten en hun attributen aan bestaande HTML-elementen en -attributen. Voor inleidende informatie over linting van aangepaste componenten, zie Linting van Aangepaste Componenten.

Het volgende voorbeeld toont een complete mapping van een aangepaste component:

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

Het voorbeeld toont de mapping van de aangepaste component custom-component naar html-element met attributen custom-attribute-1 gemapt naar html-element-attribute1 en custom-attribute-2 gemapt naar <text>, wat een speciale attribuutwaarde is die custom-attribute-2 naar de tekstinhoud van het uitvoer-HTML-element kaart. Voor meer informatie, zie De Speciale <text> Waarde.

De speciale aria-* waarde geeft aan dat alle ARIA-attributen op het aangepaste element moeten worden gekopieerd naar het uitvoer-HTML-element. Zie Gebruik van aria-* voor meer informatie.

De replace eigenschap geeft aan of custom-component moet worden verwijderd uit de uitvoer-DOM-boom, waar Angular en JavaScript aangepaste elementen deel van uitmaken. De standaardwaarde is hetzelfde als de standaard voor de gebruikte technologie. Dat wil zeggen, true voor Angular en HTML, false voor JSX, TSX en Vue.

Als de aangepaste component geen attributen-mapping vereist, kun je dit verkorte formaat gebruiken dat custom-component naar html-elementmapt:

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

De rules Eigenschap

De rules eigenschap verwijst naar een LinterRuleset object, dat je toestaat om regels in of uit te schakelen op basis van hun regel-ID. Voor meer informatie over de toegankelijkheidsregels, zie Axe DevTools Linter Accessibility Rules.

Bijvoorbeeld, de volgende configuratie schakelt de image-alt regel in en schakelt de tabindex regel uit:

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

Voor een lijst van regels waartegen de server controleert, zie Axe DevTools Linter Accessibility Rules

De exclude Eigenschap

De exclude eigenschap kan worden gebruikt om Axe Linter te vertellen bepaalde bestanden over te slaan bij het linten. Zie Configuratiebestand in de documentatie voor Axe DevTools Linter Connector voor meer informatie.

De tags Eigenschap

De tags eigenschap is een array van strings of *tags*. Elke tag is gekoppeld aan een of meer toegankelijkheidsregels, dus door hier meerdere tags op te geven, kun je veel verschillende toegankelijkheidsregels inschakelen (en alle regels uitschakelen die niet zijn getagd met de gespecificeerde tags). De tags komen meestal overeen met verschillende toegankelijkheidsstandaarden en elke regel kan lid zijn van veel verschillende tags.

Het Status Eindpunt (/status)

De Health Check Endpoint (/healthcheck)

Om te controleren of de server draait en om het versienummer op te vragen, stuur een GET verzoek naar de health check endpoint. Een voorbeeldverzoek wordt hieronder getoond:

GET /healthcheck

Als de server draait, zal deze reageren met het versienummer van de server, zoals in het onderstaande voorbeeld:

{
  "version": "4.10.3"
}

De Enterprise Billing Endpoint (/billing/enterprise)

De enterprise billing endpoint stelt u in staat om totale gebruiksinformatie voor uw onderneming te verkrijgen, evenals het gebruik uitgesplitst per individuele API-sleutel. De endpoint reageert op een GET verzoek en vereist dat u een jaar en maand (hier, mei 2022) specificeert, zoals hieronder wordt getoond:

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

Het verzoek vereist een authorization header met uw API-sleutel. Zie Een API-sleutel verkrijgen voor meer informatie.

Standaard retourneert de server gegevens voor één maand, maar u kunt de optionele months=<number-of-months-data> querystring gebruiken om meer op te geven. De months parameter kan variëren van 1 tot 12 (inclusief). Het onderstaande voorbeeld toont hoe u gegevens voor drie maanden kunt verkrijgen, te beginnen vanaf mei 2022:

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

Respons

De SaaS linter-server reageert met een JSON-object dat twee objecten bevat. Het eerste is een summary object, en het tweede, api_keys, is een verzameling objecten die informatie bevat over het gebruik van de linterservice door elke API-sleutel.

Een voorbeeld van een responsobject wordt hieronder getoond:

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

Als er geen gegevens zijn voor de opgegeven periode, ziet de respons er zo uit:

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

Het summary Object

Het summary object geeft u informatie over het totale aantal regels dat is gecheckt en hoeveel scans zijn geïnitieerd door gebruikers binnen de onderneming.

De api_keys Array

De api_keys array bevat objecten die uit de volgende eigenschappen bestaan:

De Gebruikersfactureringsendpoint (/billing/user)

Dit endpoint, het gebruiksfactureringsendpoint, stelt je in staat factureringsinformatie voor een gebruiker te verkrijgen voor alle API-sleutels die zijn gebruikt om toegang te krijgen tot de SaaS-server. De standaard is om gegevens van één maand te retourneren.

Het volgende voorbeeld toont een verzoek voor mei 2022 voor de gebruiker vertegenwoordigd door de verstrekte API-sleutel (in de authorization header):

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

Net als de andere factureringsendpoints, kun je een optionele months querytekenreeks specificeren zoals hieronder getoond:

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

Het volgende toont een voorbeeld van een responsobject:

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

Als de gebruiker geen gebruik had tijdens de opgegeven periode, zou je deze respons ontvangen:

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

Het responsobject bevat twee objecten, summary en api_keys behorend tot de gebruiker. Voor meer informatie, zie Het summary Object en Het api_keys Array hierboven.

De API-sleutelfactureringsendpoint (/billing/key)

Om gebruiksgegevens voor een API-sleutel te verkrijgen, kun je het API-sleutelfactureringsendpoint gebruiken. Je moet het jaar en de maand specificeren zoals hieronder getoond:

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

Net als de andere factureringsendpoints, kun je een optionele months querytekenreeks specificeren zoals hieronder getoond:

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

Een voorbeeld van een responsobject wordt hieronder getoond:

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

Als er geen regels werden gecontroleerd tijdens de opgegeven periode met de API-sleutel die is opgegeven in de Authorization header, zou je een respons zoals de volgende ontvangen:

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

De name waarde is de naam die aan de API-sleutel is toegewezen toen deze werd aangemaakt. De andere waarden, total_lines_linted en total_scans, geven het aantal regels aan dat werd gecontroleerd in de opgegeven periode en het totale aantal scans dat door deze API-sleutel in de opgegeven periode werd gestart.

Snelle URL-referentie

Belangrijke URL's voor gebruik met Axe DevTools Linter SaaS zijn als volgt:

Zie Een API-sleutel voor Axe DevTools Linter SaaS verkrijgen voor meer informatie over de vereiste stappen om een API-sleutel te verkrijgen.