Resultaten Programmeren

De downloadbare rapporten REST-service stelt u in staat een samenvatting van uw Axe Developer Hub toegankelijkheidsresultaten als JSON-gegevens 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 uw project of voeg een nieuwe API-sleutel toe in de Axe Account Portal. Kies een Axe Developer Hub API-sleutel als uw 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 u wilt downloaden. Vind uw project-ID in Axe Developer Hub.

U kunt twee optionele parameters gebruiken om uw 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: Specificeert de project-ID voor het projectrapport dat u 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 terug voor de opgegeven Git-branchnaam.
    • 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 terug voor de opgegeven Git commit SHA.
    • Voorbeeld gebruik: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&commit_sha=<GIT_COMMIT_SHA>

Voorbeeld curl aanvraag

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

Splits de problemen op 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 verstrekte waarde 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 reactie begeleiden.

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 reactie begeleiden.

De gebruikte SHA-waarde bij 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 opgegeven waarde voor branch_name bestaat niet

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

Antwoordtekst

{
  "error": "Session not found"
}

De verstrekte waarde voor project_id bestaat niet

Deze foutreactie is hetzelfde als de vorige 404 fouten.

Antwoordtekst

{
  "error": "Session not found"
}

Een 202 Processing reactie afhandelen

Dit demonstratiescript laat zien hoe u curl kunt gebruiken om uw rapport opnieuw aan te vragen als u een 202 Processing reactie ontvangt. Aangezien testsuites talrijke toegankelijkheidsproblemen kunnen vinden, kan ons systeem extra tijd nodig hebben om alle resultaten te verwerken voordat het rapport gereed is om te downloaden. We raden aan om onderstaand voorbeeld te gebruiken om een script te maken dat voortdurend opnieuw probeert en kijkt of de resultaten al beschikbaar zijn. Het zal het verzoek tot 20 keer opnieuw proberen, met een pauze van vijf seconden tussen de pogingen.

Het voorbeeld vereist dat de API_KEY omgevingsvariabele wordt ingesteld op uw API-sleutel en PROJECT_ID wordt ingesteld op uw 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