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), HTL (.htl) en Markdown (.md en .markdown) bestanden controleren.

De REST-eindpunten

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

De REST-eindpunten zijn als volgt:

De Lint Endpoint (/lint-source)

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

Verzoek

Om dit endpoint te gebruiken, maakt u een POST verzoek naar het lint endpoint van de server, zoals is weergegeven in het onderstaande voorbeeld:

POST /lint-source

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

Content-Type: application/json

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

Authorization: <YOUR API KEY>

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

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-voorbeeld heeft een toegankelijkheidsfout: de kopniveaus hebben een gat tussen de eerste kop (kopniveau 1) en de tweede kop (kopniveau 3). Om de reactie van de server op deze fout te zien, zie het Respons gedeelte 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 aanhalingstekens 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 moet worden gebruikt. Meestal zal Axe DevTools Linter de bestandsextensie op de filename eigenschap gebruiken om de linter te kiezen. Als u liever de linter zelf wilt specificeren, kunt u de language eigenschap en de waarden die in de bovenstaande tabel zijn gespecificeerd gebruiken. In dit geval moet u nog steeds een filename als verplicht parameter specificeren, maar language heeft voorrang op de extensie van de bestandsnaam. Bijvoorbeeld, als u een filename van "somefile.html" en een language van md opgeeft, zal de server de Markdown-linter gebruiken.

Respons

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 respons JSON-object voor een bron die een fout heeft (merk op dat errors een lijst 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

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

{
  "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 ontbrekende lang attribuut op het html element), er geen fouten worden geretourneerd omdat die regel is uitgeschakeld.

Het global-components Object

Het global-components object mapt aangepaste componenten en hun attributen naar bestaande HTML-elementen en attributen. Voor inleidende informatie over het linten 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 map naar de tekstinhoud van het uitvoer HTML-element. 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 verwijderd moet worden uit de output-DOM-boom, wat Angular en JavaScript-op-maat-componenten bevatten. De standaard 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 attribuutmapping vereist, kunt u dit verkorte formaat gebruiken dat custom-component naar html-element map.

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

De rules Eigenschap

De rules eigenschap verwijst naar een LinterRuleset object, waarmee u regels kunt in- of uitschakelen op basis van hun regel-ID. Voor meer informatie over de toegankelijkheidsregels, zie Axe DevTools Linter Accessibility Rules.

Het volgende configuratievoorbeeld schakelt de image-alt regel in en schakelt de tabindex regel uit:

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

Voor een lijst met 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 lijst van strings of *tags*. Elke tag is verbonden met een of meer toegankelijkheidsregels, dus door hier meerdere tags op te geven, kunt u veel verschillende toegankelijkheidsregels inschakelen (en alle regels uitschakelen die niet zijn getagd met de opgegeven tags). De tags komen doorgaans overeen met verschillende toegankelijkheidsnormen, en elke regel kan lid zijn van veel verschillende tags.

De Status Endpoint (/status)

De Health Check Endpoint (/healthcheck)

Om te controleren of de server draait en om het versienummer te retourneren, stuurt u een GET verzoek naar het health check endpoint. Een voorbeeldverzoek is hieronder weergegeven:

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)

Het facturatie-eindpunt voor ondernemingen stelt u in staat om totale gebruiksinformatie voor uw onderneming te verkrijgen, en het gebruik uitgesplitst per individuele API-sleutels. Het eindpunt reageert op een GET-aanvraag en vereist dat u een jaar en maand specificeert (hier mei 2022), zoals hieronder weergegeven:

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

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

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

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

Respons

De SaaS-linterserver reageert met een JSON-object dat twee objecten bevat. Het eerste is een summary-object, en het tweede, api_keys, is een verzameling objecten met informatie 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 gelinte lijnen en hoeveel scans door gebruikers binnen de onderneming werden gestart.

De api_keys-array

De api_keys-array bevat objecten samengesteld uit de volgende eigenschappen:

Het gebruikersfacturatie-eindpunt (/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 aanvraag 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 facturatie-eindpunten, kunt u een optionele months-query-string specificeren zoals hieronder weergegeven:

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 antwoordobject bevat twee objecten, summary en api_keys, die tot de gebruiker behoren. Voor meer informatie, zie Het summary-object en De api_keys-array hierboven.

Het API-sleutelfacturatie-eindpunt (/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 facturatie-eindpunten, kunt u een optionele months-query-string specificeren zoals hieronder weergegeven:

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 lijnen werden gelint gedurende de gespecificeerde periode met de API-sleutel die in de Authorization-header is opgegeven, ontvangt u een antwoord zoals het volgende:

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

De name-waarde is de naam die aan de API-sleutel is toegekend toen deze werd aangemaakt. De andere waarden, total_lines_linted en total_scans, specificeren het aantal gelinte lijnen in de gespecificeerde periode en het totale aantal scans dat door deze API-sleutel in de gespecificeerde 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 stappen die nodig zijn om een API-sleutel te verkrijgen.