Resultaten Programmeren

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

• API-sleutel - Vind een persoonlijke API-sleutel die overeenkomt met je project of voeg een nieuwe API-sleutel toe in het Axe Account Portaal. 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 - Geef de project-ID op 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.

Verzoeksamenvatting

• Endpoint: https://axe.deque.com/api-pub/watcher/downloadable/report
• Verzoek: GET
• Headers (Vereist):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json
• Queryparameters:
  • project_id (Vereist)
    • Beschrijving: Geeft de project-ID op voor het verslag van het project dat je wilt downloaden. Deze parameter is vereist.
    • Voorbeeldgebruik: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>
  • branch_name (Optioneel)
    • Beschrijving: Geeft het downloadbare rapport terug voor de opgegeven naam van de Git-branch.
    • Voorbeeldgebruik: 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 terug voor de opgegeven Git commit SHA.
    • Voorbeeldgebruik: 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 Reactielichaam

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

Antwoord Object

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

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 geassocieerd met de test:

devhub_summary Object

Bevat samenvattende informatie over gevonden toegankelijkheidsproblemen:

issue_count_by_impact Object

Geeft problemen weer 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 wordt gegenereerd, en u moet uw aanvraag opnieuw proberen na 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 de 401 Unauthorized respons 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 de 404 Not Found respons 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 is uitgevoerd voor deze Git-commit. Let op, dit is dezelfde fout als geretourneerd met een branch-naam die niet bestaat. (Zie de volgende fout.)

Antwoordtekst

{
  "error": "Session not found"
}

De opgegeven waarde voor branch_name bestaat niet

Deze foutreactie is dezelfde als de vorige fout (als de opgegeven SHA met de commit_sha queryparameter niet bestaat in de axe Developer Hub gegevens).

Antwoordtekst

{
  "error": "Session not found"
}

De waarde die is opgegeven voor project_id bestaat niet

Deze foutreactie is dezelfde als de vorige 404 fouten.

Antwoordtekst

{
  "error": "Session not found"
}

Omgaan met een 202 Processing Response

Dit demonstratie-shellscript laat zien hoe curl te gebruiken om uw rapport opnieuw aan te vragen als u een 202 Processing respons ontvangt. Omdat testsuites talrijke toegankelijkheidsschendingen kunnen vinden, kan ons systeem extra tijd nodig hebben om alle resultaten te verwerken voordat het rapport klaar is om te downloaden. We raden aan het onderstaande voorbeeld te gebruiken om een script te maken dat constant opnieuw probeert en nagaat of de resultaten al beschikbaar zijn. Het zal maximaal 20 keer de aanvraag opnieuw proberen, met een vertraging van vijf seconden tussen de pogingen.

Het voorbeeld vereist dat de API_KEY omgevingsvariabele is ingesteld op uw API-sleutel en PROJECT_ID op uw project-ID moet zijn ingesteld.

#!/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