Riferimento all'API REST di Axe DevTools Linter

Axe DevTools Linter ti consente di controllare il codice per problemi di accessibilità utilizzando un'API REST. Crei un oggetto di richiesta HTTP che contiene le righe di codice che desideri controllare (nel corpo della richiesta come oggetto JSON), e il server restituisce un oggetto JSON di risposta che indica eventuali problemi di accessibilità trovati dal server.

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

Gli endpoint REST

Il server fornisce sei endpoint REST. Il primo endpoint, (/lint-source), risponde a richieste POST e controlla il tuo codice per problemi di accessibilità. Il secondo endpoint, (/status), risponde a richieste GET e mostra se il server è disponibile con un codice di risposta 200 che indica che il server è in ascolto. Il terzo endpoint, (/healthcheck), risponde a richieste GET, indica se il server è in esecuzione e restituisce il numero di versione del server in esecuzione. Gli altri tre endpoint consentono agli utenti della versione SaaS di ottenere informazioni sull'uso per la loro azienda nel suo complesso (/billing/enterprise), per i loro utenti (/billing/user) e per le loro chiavi API (/billing/key).

Gli endpoint REST sono i seguenti:

L'Endpoint Lint (/lint-source)

L'endpoint lint è l'endpoint di servizio principale. Puoi usarlo per inviare codice a Axe DevTools Linter per controllare problemi di accessibilità. Accetta richieste POST con un corpo JSON contenente il codice da controllare.

Richiesta

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

POST /lint-source

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

Content-Type: application/json

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

Authorization: <YOUR API KEY>

Puoi saperne di più su come ottenere una chiave API in Ottenere una chiave API di Axe DevTools Linter SaaS.

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

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

Il campione di Markdown sopra ha un errore di accessibilità: i livelli di intestazione hanno un vuoto tra la prima intestazione (livello di intestazione 1) e la seconda intestazione (livello di intestazione 3). Per vedere la risposta del server a questo errore, consulta la sezione Risposta qui sotto.

L'oggetto JSON della richiesta

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

La stringa source nell'oggetto JSON della richiesta è il codice che vuoi controllare. Devi eseguire l'escape di tutte le virgolette e le nuove righe (precedi con una barra inversa).

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 sulla proprietà filename per scegliere il linter. Se preferisci specificare quale linter utilizzare, puoi usare la proprietà language e i valori specificati nella tabella sopra. In questo caso, devi comunque specificare un filename come parametro richiesto, ma language ha la precedenza sull'estensione del file. Ad esempio, se specifichi un filename come "somefile.html" e un language come md, il server utilizzerà il linter Markdown.

Risposta

Il server risponde con un codice di risposta 200 indipendentemente dalla presenza di errori di accessibilità. Devi esaminare il JSON nel corpo della risposta per vedere se ci sono errori.

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

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

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

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

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

L'oggetto config

Puoi specificare una proprietà config se vuoi avere più controllo sulle regole che Axe DevTools Linter utilizza per controllare il tuo codice sorgente alla ricerca di errori di accessibilità.

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

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

L'oggetto global-components

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

Il seguente esempio mostra una mappatura completa di un componente personalizzato:

{
  "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 testuale dell'elemento HTML di output. Per maggiori informazioni, vedi Il Valore Speciale <text>.

Il valore speciale aria-* indica che tutti gli attributi ARIA sull'elemento personalizzato dovrebbero essere copiati all'elemento HTML di output. Vedi Utilizzo di aria-* per maggiori informazioni.

La proprietà replace indica se custom-component dovrebbe essere rimosso dall'albero DOM di output, che includono Angular e elementi personalizzati JavaScript. Il valore di default è lo stesso di quello per la tecnologia usata. Cioè, true per Angular e HTML, false per JSX, TSX e Vue.

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

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

La Proprietà rules

La proprietà rules fa riferimento a un oggetto LinterRuleset, che ti permette di abilitare o disabilitare le regole tramite il loro ID. Per ulteriori informazioni sulle regole di accessibilità, vedi Regole di Accessibilità di Axe DevTools Linter.

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 verifica, vedere Regole di Accessibilità di Axe DevTools Linter

La Proprietà exclude

La proprietà exclude può essere usata per dire ad Axe Linter di ignorare certi file durante il linting. Per maggiori informazioni, vedere File di Configurazione nella documentazione del Connettore di Axe DevTools Linter.

La Proprietà tags

La proprietà tags è 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 qualsiasi regola che non è contrassegnata con i tag specificati). I tag tipicamente corrispondono a diversi standard di accessibilità, e ogni regola può appartenere a molti tag diversi.

Il Endpoint di Stato (/status)

Il Endpoint di Verifica dello Stato (/healthcheck)

Per verificare se il server è in esecuzione e restituire il numero di versione, invia una richiesta GET all'endpoint di verifica dello stato. Un esempio di richiesta è mostrato di seguito:

GET /healthcheck

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

{
  "version": "4.10.3"
}

Il Endpoint di Fatturazione per le Aziende (/billing/enterprise)

L'endpoint di fatturazione per le aziende ti consente di ottenere informazioni sull'uso totale della tua azienda e l'uso suddiviso per singole chiavi API. L'endpoint risponde a una richiesta GET e richiede di specificare un anno e un mese (qui, maggio 2022), come mostrato di seguito:

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

La richiesta richiede un'intestazione authorization con la tua chiave API. Vedere Ottenere una Chiave API per maggiori informazioni.

Per impostazione predefinita, il server restituisce un mese di dati, ma puoi usare la stringa di query opzionale months=<number-of-months-data> per specificare di più. Il parametro months può variare da 1 a 12 (inclusi). L'esempio di seguito 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 oggetto summary, e il secondo, api_keys, è una raccolta di oggetti che contengono informazioni sull'uso del servizio linter da parte di ogni chiave API.

Un esempio di oggetto di risposta è mostrato di seguito:

{
  "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 ci sono dati per il periodo di tempo specificato, la risposta sarà simile a questa:

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

L'Oggetto summary

L'oggetto summary ti fornisce informazioni sul numero totale di righe analizzate e su quanti controlli sono stati iniziati dagli utenti all'interno dell'azienda.

L'Array api_keys

L'array api_keys contiene oggetti composti dalle seguenti proprietà:

L'Endpoint di Fatturazione Utente (/billing/user)

Questo endpoint, l'endpoint di fatturazione dell'uso, ti consente di ottenere informazioni di fatturazione per un utente per tutte le chiavi API utilizzate per accedere al server SaaS. Il predefinito è che vengano restituiti i dati di un mese.

Il seguente esempio 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, puoi specificare una stringa di query opzionale months come mostrato di seguito:

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

Di seguito viene mostrato un esempio di oggetto di 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 avesse utilizzato alcun servizio nel periodo specificato, riceveresti questa risposta:

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

L'oggetto di risposta contiene due oggetti, summary e api_keys appartenenti all'utente. Per maggiori informazioni, vedi L'Oggetto summary e L'Array api_keys sopra.

L'Endpoint di Fatturazione della Chiave API (/billing/key)

Per ottenere i dati di utilizzo per una chiave API, puoi 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, puoi specificare una stringa di query opzionale months come mostrato di seguito:

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

Di seguito è mostrato un esempio di oggetto di risposta:

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

Se non ci fossero linee elaborate durante il periodo specificato utilizzando la chiave API specificata nell'intestazione Authorization, riceveresti una risposta come la seguente:

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

Il valore name è il nome assegnato alla chiave API quando è stata creata. Gli altri valori, total_lines_linted e total_scans, specificano il numero di righe che sono state elaborate nel periodo specificato e il numero totale di scansioni iniziate da questa chiave API nel periodo specificato.

Riferimento Rapido URL

Gli URL importanti per l'uso con Axe DevTools Linter SaaS sono i seguenti:

Vedi Ottenere una Chiave API Axe DevTools Linter SaaS per maggiori informazioni sui passaggi necessari per ottenere una chiave API.