Resultaten Programmeren

De downloadbare rapporten REST-service stelt je in staat om een samenvatting van je Axe Developer Hub toegankelijkheidsresultaten als JSON-gegevens te downloaden, voor verdere verwerking of import in andere software. De GET-service heeft twee verplichte parameters:

• API-sleutel - Vind een persoonlijke API-sleutel die overeenkomt met je project of voeg een nieuwe API-sleutel toe in de Axe Account Portal. Kies een Axe Developer Hub API-sleutel als je project de web-API's, CLI of Watcher gebruikt. Gebruik een Axe DevTools Mobile API-sleutel voor mobiele projecten.
• Project-ID - Verstrek het project-ID voor de bijbehorende projectgegevens die je wilt downloaden. Vind je project-ID in Axe Developer Hub.

Je kunt twee optionele parameters gebruiken om je query te beperken tot een specifieke Git-branch of een specifieke Git commit SHA.

Samenvatting aanvraag

• Endpoint: https://axe.deque.com/api-pub/watcher/downloadable/report
• aanvraag: GET
• Headers (Vereist):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json
• Query parameters:
  • project_id (Vereist)
    • Beschrijving: Geeft het project-ID op voor het projectrapport dat je wilt downloaden. Deze parameter is vereist.
    • Voorbeeld gebruik: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>
  • branch_name (Optioneel)
    • Beschrijving: Geeft het downloadbare rapport voor de opgegeven Git-branchnaam terug.
    • Voorbeeld gebruik: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&branch_name=<GIT_BRANCH>
  • commit_sha (Optioneel)
    • Beschrijving: Geeft het downloadbare rapport voor de opgegeven Git-commit-SHA terug.
    • Voorbeeld gebruik: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&commit_sha=<GIT_COMMIT_SHA>

Voorbeeld curl-verzoek

curl -L -H 'Accept: application/json' -H 'X-API-Key: <DEQUE_API_KEY>' 'https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>'

Voorbeeld van Respons Body

{
  "report_id": "a4990926-3014-4799-aa39-7aca31fce412",
  "source": {
    "product_name": "axe-devtools-html",
    "product_component_name": "axe-devtools-watcher",
    "product_version": "3.20.2"
  },
  "test_details": {
    "test_id": "da0c79a5-6f1e-4692-a255-5757629208fa",
    "start_date": "2025-05-05T20:02:31.883Z",
    "end_date": "2025-05-05T20:02:42.789Z"
  },
  "commit": {
    "sha": "f73ea5a02386b359ffa79a76473f7a5ad41759d5",
    "author": "John Doe",
    "author_email": "john.doe@example.com",
    "message": "Merge pull request #233 from deque/221-add-examples-for-using-global-config-fields-2",
    "branch_name": "main",
    "repository_url": "https://github.com/dequelabs/watcher-examples.git",
    "tag": null
  },
  "devhub_summary": {
    "issue_count_total": 17,
    "issue_count_by_impact": {
      "critical": 0,
      "serious": 2,
      "moderate": 15,
      "minor": 0
    },
    "issue_count_by_rule": [
      {
        "severity": "serious",
        "rule_id": "color-contrast",
        "rule_help": "Elements must meet minimum color contrast ratio thresholds",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/color-contrast?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "heading-order",
        "rule_help": "Heading levels should only increase by one",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/heading-order?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "landmark-one-main",
        "rule_help": "Document should have one main landmark",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/landmark-one-main?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "page-has-heading-one",
        "rule_help": "Page should contain a level-one heading",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/page-has-heading-one?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "region",
        "rule_help": "All page content should be contained by landmarks",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/region?application=axeAPI",
        "count": 9
      }
    ]
  }
}

Responsobject

De volgende secties beschrijven de JSON-objecten in het responsbody.

Topniveau Structuur

source Object

Bevat informatie over het product dat het rapport genereerde:

test_details Object

Bevat informatie over de testuitvoering:

commit Object

Bevat informatie over de Git-commit gekoppeld aan de test:

devhub_summary Object

Bevat samenvattende informatie over gevonden toegankelijkheidsproblemen:

issue_count_by_impact Object

Analyseert problemen per impactniveau:

issue_count_by_rule Array

Elk object in deze array vertegenwoordigt een regel met de volgende structuur:

Aanvullende reacties

202 Processing

Deze reactie geeft aan dat het rapport nog gegenereerd wordt en dat u uw verzoek opnieuw moet indienen na enige tijd te wachten.

Antwoordtekst

{
  "message": "Report is still processing",
  "state": "PROCESSING"
}

400 Bad Request

De waarde die is opgegeven voor commit_sha is geen SHA-1-waarde.

Antwoordtekst

{
  "error": "commit_sha must be a valid SHA-1 hash"
}

401 Unauthorized

Een van de volgende foutmeldingen zal het 401 Unauthorized-antwoord vergezellen.

De opgegeven API-sleutel is niet geldig

Antwoordtekst

{
  "error": "Invalid API key"
}

Er is geen vereiste header met een API-sleutel:

Antwoordtekst

{
  "error": "X-API-Key or Authorization header required"
}

404 Not Found

Een van de volgende foutmeldingen zal het 404 Not Found-antwoord vergezellen.

De SHA-waarde gebruikt met commit_sha kon niet worden gevonden

Deze fout geeft aan dat er geen gegevens zijn voor deze SHA in de Axe Developer Hub-gegevens, wat meestal betekent dat de testsuite niet tegen deze Git-commit is uitgevoerd. Merk op dat dit dezelfde fout is als die wordt geretourneerd bij een branchnaam die niet bestaat. (Zie de volgende fout.)

Antwoordtekst

{
  "error": "Session not found"
}

De aangeleverde waarde voor branch_name bestaat niet

Deze foutreactie is hetzelfde als de vorige fout (als de SHA die met de commit_sha queryparameter is geleverd, niet bestaat in de Axe Developer Hub gegevens).

Antwoordtekst

{
  "error": "Session not found"
}

De waarde die is geleverd voor project_id bestaat niet

Deze foutreactie is hetzelfde als de vorige 404 fouten.

Antwoordtekst

{
  "error": "Session not found"
}

Afhandelen van een 202 Processing-antwoord

Dit demonstratiescript laat zien hoe je curl kunt gebruiken om je rapport opnieuw op te vragen als je een 202 Processing-antwoord ontvangt. Aangezien testsuites mogelijk talrijke toegankelijkheidsschendingen ontdekken, kan ons systeem extra tijd nodig hebben om alle resultaten te verwerken voordat het rapport klaar is om te downloaden. We raden aan om het onderstaande voorbeeld te gebruiken om een script te maken dat voortdurend opnieuw probeert en kijkt of de resultaten al beschikbaar zijn. Het zal tot 20 keer het verzoek opnieuw indienen, met een vertraging van vijf seconden tussen pogingen.

Het voorbeeld vereist dat de API_KEY omgeving variabele is ingesteld op je API-sleutel en PROJECT_ID is ingesteld op je project-ID.

#!/bin/bash

URL="https://axe.deque.com/api-pub/watcher/downloadable/report"
MAX_ATTEMPTS=20
DELAY=5
TEMP_FILE=$(mktemp)

for ((i=1; i<=MAX_ATTEMPTS; i++)); do
    echo "Attempt $i..."
    
    # Get both status and response
    STATUS=$(curl -s -w '%{http_code}' -L -H "Accept: application/json" -H "X-API-Key: $API_KEY" -o "$TEMP_FILE" "$URL?project_id=$PROJECT_ID")
    
    case $STATUS in
        200)
            echo "Success!"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE"
            exit 0
            ;;
        202)
            echo "Still processing, waiting ${DELAY}s..."
            sleep $DELAY
            ;;
        *)
            echo "Error: HTTP $STATUS"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE"
            exit 1
            ;;
    esac
done

echo "Timeout after $MAX_ATTEMPTS attempts"
rm "$TEMP_FILE"
exit 1