Riferimento all'API REST di axe DevTools Linter

Axe DevTools Linter consente di verificare il codice per problemi di accessibilità utilizzando una API REST. Si crea un oggetto di richiesta HTTP contenente le righe di origine che si desidera controllare (nel corpo della richiesta come oggetto JSON) e il server restituisce un oggetto JSON di risposta che indica eventuali problemi di accessibilità rilevati dal server.

Il server può controllare i file React (.js, .jsx, .ts e .tsx), Vue (.vue), Angular (.component.html), HTML (.html, .htm e .xhtml) e Markdown (.md e .markdown).

Gli endpoint REST

Il server fornisce sei endpoint REST. Il primo endpoint, (/lint-source), risponde alle richieste e controlla il codice per individuare eventuali problemi di accessibilità. POST Il secondo endpoint, (/status), risponde alle richieste e mostra se il server è disponibile con un codice di risposta 200 che indica che il server è in ascolto. GET Il terzo endpoint, (/healthcheck), risponde alle richieste, indica se il server è in esecuzione e restituisce il numero di versione del server in esecuzione. GET I restanti tre endpoint consentono agli utenti dell'edizione SaaS di ottenere informazioni sull'utilizzo per la propria azienda nel suo complesso (/billing/enterprise), per i propri utenti (/billing/user) e per le proprie chiavi API (/billing/key).

Gli endpoint REST sono i seguenti:

Il punto finale di Lint (/lint-source)

L'endpoint Lint è l'endpoint del servizio primario. Puoi utilizzarlo per inviare codice ad axe DevTools Linter per verificare eventuali problemi di accessibilità. Accetta richieste con un corpo JSON contenente il codice da controllare. POST

Richiesta

Per utilizzare questo endpoint, è necessario creare una richiesta all'endpoint lint del server, come mostrato nell'esempio seguente: POST

POST /lint-source

È necessario includere anche un'intestazione per indicare al server che il corpo della richiesta contiene un oggetto JSON. Content-Type

Content-Type: application/json

Se utilizzi axe DevTools Linter SaaS, dovrai includere un'intestazione con la tua chiave API, come mostrato di seguito: Authorization

Authorization: <YOUR API KEY>

Per ulteriori informazioni su come ottenere una chiave API, consulta Ottenere una chiave API SaaS di axe DevTools Linter.

Il corpo della richiesta dovrebbe contenere il codice (all'interno di un oggetto JSON) che si desidera controllare. Ad esempio, il seguente oggetto JSON controlla un campione di markdown:

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

L'esempio Markdown sopra riportato presenta un errore di accessibilità: i livelli di intestazione presentano uno spazio tra la prima intestazione (livello di intestazione 1) e la seconda intestazione (livello di intestazione 3). Per visualizzare la risposta del server a questo errore, vedere la sezione Risposta di seguito.

Oggetto richiesta JSON

La tabella seguente mostra le proprietà utilizzate con l'oggetto richiesta JSON:

La stringa nell'oggetto JSON della richiesta è il codice che si desidera controllare. source È necessario eseguire l'escape di tutte le virgolette e delle nuove righe (precedute da una barra rovesciata).

La stringa language può assumere uno dei seguenti valori:

Il server utilizza le proprietà filename e language per determinare quale linter utilizzare. Solitamente, axe DevTools Linter utilizzerà l'estensione del file nella proprietà filename per scegliere il linter. Se invece si desidera specificare il linter da utilizzare, è possibile utilizzare la proprietà language e i valori specificati nella tabella sopra. In questo caso, è comunque necessario specificare un filename come parametro obbligatorio, ma language ha la precedenza sull'estensione del nome file. Ad esempio, se si specifica un filename di "somefile.html" e un language di md , il server utilizzerà il linter Markdown.

Risposta

Il server risponde con un codice di risposta 200 indipendentemente dal fatto che vi siano o meno errori di accessibilità. È necessario esaminare il codice JSON nel corpo della risposta per verificare se sono presenti errori.

Se il codice non contiene errori, l'oggetto di risposta JSON è il seguente:

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

L'esempio seguente mostra l'oggetto JSON di risposta per la sorgente che presenta un errore (nota che errors è un array di error oggetti).

{
  "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 oggetto

L' errors array contiene error oggetti che hanno le seguenti proprietà:

L' config oggetto

Puoi specificare una proprietà se desideri un maggiore controllo sulle regole utilizzate da axe DevTools Linter per verificare la presenza di errori di accessibilità nel codice sorgente. config

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

L'esempio precedente mostra che, nonostante la sorgente abbia un errore di accessibilità (un attributo mancante sull' lang elemento html ), non verranno restituiti errori perché la regola è stata disattivata.

L' global-components oggetto

L'oggetto global-components mappa i componenti personalizzati e i loro attributi agli elementi e agli attributi HTML esistenti. Per informazioni introduttive sul linting dei componenti personalizzati, vedere Linting dei componenti personalizzati.

L'esempio seguente mostra una mappatura completa dei componenti personalizzati:

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

L'esempio mostra la mappatura dal componente personalizzato custom-component a html-element con attributi custom-attribute-1 mappati a html-element-attribute1 e custom-attribute-2 mappati a <text>, che è un valore di attributo speciale che mappa custom-attribute-2 al contenuto di testo dell'elemento HTML di output. Per ulteriori informazioni, vedere Il valore speciale <testo>.

Per maggiori informazioni consultare lo speciale aria-* value indicates that all ARIA attributes on the custom element should be copied to the output HTML element. See Using aria-* .

La proprietà replace indica se custom-component deve essere rimossa dall'albero DOM di output, che include elementi personalizzati di Angular e JavaScript. L'impostazione predefinita è la stessa della tecnologia utilizzata. Cioè true per Angular e HTML, false per JSX, TSX e Vue.

Se il componente personalizzato non richiede la mappatura degli attributi, puoi utilizzare questo formato abbreviato che mappa custom-component a html-element:

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

La rules Proprietà

rules La proprietà fa riferimento a LinterRuleset un oggetto che consente di abilitare o disabilitare le regole in base al loro ID. Per ulteriori informazioni sulle regole di accessibilità, vedere axe DevTools Linter Accessibility Rules.

Ad esempio, la seguente configurazione abilita la regola image-alt e disabilita la regola tabindex :

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

Per un elenco delle regole che il server controlla, vedere axe DevTools Linter Accessibility Rules

La exclude Proprietà

La proprietà exclude può essere utilizzata per indicare ad axe DevTools Linter di saltare determinati file durante il linting. Per ulteriori informazioni, vedere File di configurazione nella documentazione di axe DevTools Linter Connector.

La tags Proprietà

La tags proprietà è un array di stringhe o tag. Ogni tag è associato a una o più regole di accessibilità, quindi specificando più tag qui è possibile abilitare molte regole di accessibilità diverse (e disabilitare tutte le regole che non sono contrassegnate con i tag specificati). In genere i tag corrispondono a diversi standard di accessibilità e ogni regola può essere membro di molti tag diversi.

L'endpoint di stato (/status)

L'endpoint di controllo dello stato di salute (/healthcheck)

Per verificare se il server è in esecuzione e restituire il suo numero di versione, inviare una richiesta all'endpoint di controllo dello stato di salute. GET Di seguito è riportato un esempio di richiesta:

GET /healthcheck

Se il server è in esecuzione, risponderà con il numero di versione del server, come mostrato nell'esempio seguente:

{
  "version": "4.10.3"
}

endpoint di fatturazione aziendale (/billing/enterprise)

L'endpoint di fatturazione aziendale consente di ottenere informazioni sull'utilizzo totale della propria azienda e sull'utilizzo suddiviso in singole chiavi API. L'endpoint risponde a una richiesta e richiede di specificare anno e mese (in questo caso maggio 2022), come mostrato di seguito: GET

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

La richiesta richiede un'intestazione con la tua chiave API. authorization Per ulteriori informazioni, vedere Ottenere una chiave API .

Per impostazione predefinita, il server restituisce un mese di dati, ma è possibile utilizzare la stringa di query facoltativa months=<number-of-months-data> per specificarne di più. Il parametro può variare da 1 a 12 (incluso). months L'esempio seguente mostra come ottenere tre mesi di dati a partire da maggio 2022:

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

Risposta

Il server linter SaaS risponde con un oggetto JSON che contiene due oggetti. Il primo è un summary oggetto, mentre il secondo, api_keys, è una raccolta di oggetti che contengono informazioni sull'utilizzo del servizio linter da parte di ciascuna chiave API.

Di seguito è riportato un esempio di oggetto risposta:

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

Se non sono presenti dati per il periodo di tempo specificato, la risposta sarà simile a questa:

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

L' summary oggetto

L' summary oggetto fornisce informazioni sul numero totale di linee sottoposte a linting e sul numero di scansioni avviate dagli utenti all'interno dell'azienda.

La matrice api_keys

La matrice contiene oggetti composti dalle seguenti proprietà: api_keys

Endpoint di fatturazione Utente (/billing/user)

Questo endpoint, l'endpoint di fatturazione dell'utilizzo, consente di ottenere informazioni di fatturazione per un utente per tutte le chiavi API utilizzate per accedere al server SaaS. L'impostazione predefinita è che vengano restituiti i dati di un mese.

L'esempio seguente mostra una richiesta per maggio 2022 per l'utente rappresentato dalla chiave API fornita (nell'intestazione authorization ):

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

Come per gli altri endpoint di fatturazione, è possibile specificare una stringa di query facoltativa come mostrato di seguito: months

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

Di seguito è riportato un esempio di oggetto risposta:

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

Se l'utente non ha effettuato alcun utilizzo per il periodo di tempo specificato, riceveresti questa risposta:

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

L'oggetto risposta contiene due oggetti, summary e api_keys appartenenti all'utente. Per ulteriori informazioni, vedere L'oggetto summary e L'array api_keys sopra.

Endpoint di fatturazione della chiave API (/billing/key)

Per ottenere i dati di utilizzo di una chiave API, è possibile utilizzare l'endpoint di fatturazione della chiave API. È necessario specificare l'anno e il mese come mostrato di seguito:

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

Come per gli altri endpoint di fatturazione, è possibile specificare una stringa di query facoltativa come mostrato di seguito: months

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

Di seguito è riportato un esempio di oggetto risposta:

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

Se non sono state eseguite operazioni di lint di linee durante il periodo di tempo specificato utilizzando la chiave API specificata nell'intestazione, si riceverà una risposta come la seguente: Authorization

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

Il valore name è il nome assegnato alla chiave API al momento della sua creazione. Gli altri valori, total_lines_linted e total_scans, specificano il numero di linee sottoposte a linting nel periodo di tempo specificato e il numero totale di scansioni avviate da questa chiave API nel periodo di tempo specificato.

URL Riferimento rapido

Gli URL importanti da utilizzare con axe DevTools Linter SaaS sono i seguenti:

Per ulteriori informazioni sui passaggi necessari per ottenere una chiave API, vedere Ottenimento di una chiave API SaaS axe DevTools Linter .