Riferimento API dei Progetti

L'API Progetti ti consente di gestire i progetti Axe Developer Hub e la loro membership in modo programmato, utilizzando la stessa chiave API Axe Account che già usi per il resto delle API REST di Axe Developer Hub. Non ci sono credenziali separate per la gestione dei progetti. Per un'introduzione passo dopo passo, consulta Inizia con l'automazione della gestione dei progetti.

Se hai solo bisogno di scoprire l'ID di un progetto dal suo nome per poter chiamare API di Sessioni e Risultati, consulta Elenco di progetti di seguito. Se conosci già il tuo ID progetto, puoi trovarlo in Axe Developer Hub e chiamare direttamente l'API di Sessioni e Risultati.

Autenticazione

Tutte le richieste richiedono una chiave API. Forniscila utilizzando l'intestazione X-API-Key:

X-API-Key: <DEQUE_API_KEY>

Trova la tua chiave API nel Portale Account Axe. Scegli una chiave API Axe Developer Hub per progetti web o CI/CD. Scegli una chiave API Axe DevTools Mobile per progetti mobile.

Tratta la tua chiave API come un segreto: conservala in una variabile d'ambiente o nel deposito segreti della tua piattaforma CI/CD invece di codificarla direttamente nelle tue richieste.

Controllo degli accessi e permessi

• Creazione di un progetto richiede un abbonamento attivo (licenza) per il tipo di progetto. Chiunque crei un progetto diventa automaticamente il suo amministratore.
• Ruoli del progetto sono amministratore e membro. Un amministratore di progetto può aggiornare o eliminare il progetto e gestire la sua membership. Un membro del progetto può accedere al progetto ma non gestirlo o gestire la sua membership.
• Amministratori dell'Org può vedere e gestire ogni progetto dei tipi con licenza della loro organizzazione, indipendentemente dalla loro membership nei progetti. Non hanno bisogno di una licenza personale per visualizzare, aggiornare, eliminare o gestire i membri di un progetto esistente. Creare un progetto è l'unica eccezione: richiede sempre una licenza attiva, sia che il chiamante sia un amministratore dell'organizzazione o meno.
• Aggiungere un membro a un progetto non richiede che quel membro detenga una licenza. L'API li registra immediatamente come membri del progetto, ma non possono accedere al progetto finché non possiedono una licenza. L'utente target deve già appartenere all'organizzazione. Non è possibile aggiungere qualcuno che non sia già membro dell'organizzazione.
• L'eliminazione di un progetto è definitiva. Non esiste un ripristino self-service per un progetto eliminato.
• In ogni caso, la risposta è limitata al prodotto della chiave API. Una chiave API Axe Developer Hub restituisce e gestisce solo progetti Axe Developer Hub (web). Una chiave API Axe DevTools Mobile restituisce e gestisce solo progetti Axe DevTools Mobile.

Una abbonamento inattivo restituisce 401 Unauthorized.

Valori di configurazione del tipo di progetto

Ogni progetto ha un selected_project_type, e ogni tipo accetta solo un set specifico e fisso di valori di test_language / test_platform:

Il selected_project_type di un progetto è fissato quando il progetto viene creato. Per utilizzare un tipo diverso, crea un nuovo progetto.

Elenco di progetti

Restituisce l'elenco dei progetti a cui la chiave API autenticata può accedere.

Richiesta

• Endpoint: GET https://axe.deque.com/api-pub/v1/results/projects
• Intestazioni (obbligatorie):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json

Parametri di Query

Tutti i parametri di query sono opzionali.

Corpo della Risposta

Una risposta di successo restituisce un array JSON di oggetti progetto. Ogni oggetto progetto include i seguenti campi:

Le risposte possono includere campi aggiuntivi che non sono elencati qui, e nuovi campi possono essere aggiunti nel tempo. Ignora qualsiasi campo che non riconosci e non fare affidamento su campi non documentati.

Esempio di Corpo della Risposta

[
  {
    "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "webapp-ci",
    "selected_project_type": "axe-devtools-watcher",
    "test_language": "typescript",
    "test_platform": "Playwright",
    "role": "admin",
    "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "enterprise_id": "3f2b8e1a-6c4d-4f7e-9a0b-1d2c3e4f5a6b",
    "is_enterprise_project": true,
    "created_at": "2026-06-01T14:23:00.000Z",
    "updated_at": "2026-06-10T16:45:00.000Z",
    "run_by": "Jane Developer",
    "last_session_created_at": "2026-06-14T09:12:00.000Z",
    "has_git_information": true,
    "git_url": "https://github.com/example/webapp",
    "latest_session": {
      "id": "0d4a85a2-9e6f-44ef-b814-fee8412abeb0",
      "created_at": "2026-06-14T09:12:00.000Z",
      "git_branch": "main"
    }
  },
  {
    "project_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
    "name": "design-system",
    "selected_project_type": "axe-devtools-html",
    "test_language": null,
    "test_platform": null,
    "role": "admin",
    "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "enterprise_id": "3f2b8e1a-6c4d-4f7e-9a0b-1d2c3e4f5a6b",
    "is_enterprise_project": true,
    "created_at": "2026-05-20T08:00:00.000Z",
    "updated_at": null,
    "run_by": null,
    "last_session_created_at": null,
    "has_git_information": false,
    "git_url": null,
    "latest_session": null
  },
  {
    "project_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f",
    "name": "ios-app-ci",
    "selected_project_type": "axe-devtools-mobile",
    "test_language": null,
    "test_platform": "XCUITest",
    "role": "admin",
    "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "enterprise_id": "3f2b8e1a-6c4d-4f7e-9a0b-1d2c3e4f5a6b",
    "is_enterprise_project": true,
    "created_at": "2026-06-03T10:15:00.000Z",
    "updated_at": null,
    "run_by": "Jane Developer",
    "last_session_created_at": "2026-06-15T11:05:00.000Z",
    "has_git_information": false,
    "git_url": null,
    "latest_session": {
      "id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
      "created_at": "2026-06-15T11:05:00.000Z",
      "git_branch": null
    }
  }
]

Per mantenere l'esempio breve, ogni oggetto latest_session mostra solo tre dei suoi campi. L'API ne restituisce di più.

Paginazione con Cursore

La paginazione è opzionale. Non inviare né page_size né after e la risposta restituisce l'elenco completo dei tuoi progetti in una singola risposta, senza intestazione cursore.

Per scorrere invece i risultati, l'API Progetti utilizza la stessa paginazione basata su cursore di endpoint delle Sessioni. Quando ci sono più risultati oltre la pagina corrente, la risposta restituisce un valore cursore opaco nell'intestazione x-pagination-cursor. Trasmetti questo valore come parametro di query after nella tua richiesta successiva per recuperare la pagina successiva.

Quando la risposta non ha l'intestazione x-pagination-cursor, sei all'ultima pagina.

Individua un ID Progetto per Nome

Questo esempio utilizza curl e jq per trovare l'ID di un progetto dal suo nome:

curl -s \
  -H "Accept: application/json" \
  -H "X-API-Key: $API_KEY" \
  "https://axe.deque.com/api-pub/v1/results/projects" \
  | jq -r '.[] | select(.name == "webapp-ci") | .project_id'

Passa l'ID restituito al endpoint delle Sessioni per elencare le sessioni di quel progetto.

Elenco errori di risposta dei progetti

Recuperare un progetto

Restituisce un singolo progetto tramite il suo ID, nella stessa forma di Elenco di progetti.

Richiesta

• Endpoint: GET https://axe.deque.com/api-pub/v1/results/projects/{project_id}
• Intestazioni (obbligatorie):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json

Recuperare gli errori di risposta di un progetto

Creare un progetto

Richiesta

• Endpoint: POST https://axe.deque.com/api-pub/v1/results/projects
• Intestazioni (obbligatorie):
  • X-API-Key: <DEQUE_API_KEY>
  • Content-Type: application/json
  • Accept: application/json

Corpo della richiesta

Esempio di corpo della richiesta

{
  "name": "webapp-ci",
  "selected_project_type": "axe-devtools-watcher",
  "test_language": "typescript",
  "test_platform": "Playwright"
}

Corpo della Risposta

Restituisce il progetto creato, nella stessa forma di Elenco di progetti. Chi crea un progetto ne diventa automaticamente l'amministratore, quindi non è necessaria una chiamata separata per la memebership. Una creazione riuscita restituisce 201 Created.

Creare errori di risposta di un progetto

Aggiornare un progetto

Richiesta

• Endpoint: PATCH https://axe.deque.com/api-pub/v1/results/projects/{project_id}
• Intestazioni (obbligatorie):
  • X-API-Key: <DEQUE_API_KEY>
  • Content-Type: application/json
  • Accept: application/json

Corpo della richiesta

Esempio di corpo della richiesta

{
  "name": "webapp-ci-renamed"
}

Corpo della Risposta

Restituisce il progetto aggiornato, nella stessa forma di Elenco di progetti. Un aggiornamento riuscito restituisce 200 OK.

Aggiornare errori di risposta di un progetto

Eliminare un progetto

Richiesta

• Endpoint: DELETE https://axe.deque.com/api-pub/v1/results/projects/{project_id}
• Intestazioni (obbligatorie):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json

Corpo della Risposta

{ "deleted": true }

Eliminare errori di risposta di un progetto

Membership del progetto

La membership di un progetto è una sub-risorsa del progetto. Un amministratore del progetto può gestire il progetto e la sua membership. Un membro del progetto (il ruolo member nelle operazioni di membership di seguito) può accedere al progetto ma non gestirlo. Le operazioni di membership identificano gli utenti tramite il loro indirizzo email. Aggiungere un membro non richiede che tale membro possieda una licenza. L'API li registra immediatamente, ma non possono accedere al progetto finché non possiedono una licenza. L'utente di destinazione deve già appartenere alla tua organizzazione. Non puoi aggiungere qualcuno che non è già un membro dell'organizzazione.

Usa le operazioni in batch di seguito ogni volta possibile. Tutte e tre le operazioni di scrittura accettano più utenti in una singola chiamata. Questo riduce il numero di richieste che devi fare. Se gestisci la membership per una grande organizzazione, applica il backoff e riprova quando ricevi una risposta 429. Vedi 429 Too Many Requests per il modello generale.

Elenca i membri del progetto

• Endpoint: GET https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships
• Intestazioni (obbligatorie): X-API-Key: <DEQUE_API_KEY>, Accept: application/json

Corpo della Risposta

{
  "members": [
    {
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "role": "admin",
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "active_license": true,
      "created_at": "2026-06-01T14:23:00.000Z"
    }
  ]
}

Aggiungi Membri al Progetto

• Endpoint: POST https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships
• Intestazioni (obbligatorie): X-API-Key: <DEQUE_API_KEY>, Content-Type: application/json, Accept: application/json

Corpo della richiesta

{
  "user_email_role_pairs": [
    { "user_email": "sam@example.com", "role": "member" },
    { "user_email": "alex@example.com", "role": "admin" }
  ]
}

user_email è l'indirizzo email dell'Axe Account dell'utente. La corrispondenza ignora le maiuscole e gli spazi circostanti. role accetta admin o member (contributor è accettato anche come sinonimo di member). Ogni utente può comparire solo una volta in una richiesta. Aggiungere un utente che appartiene già al progetto è un'operazione nulla per quella voce: non cambia il loro ruolo esistente. Questa è un'operazione batch. Una voce non valida rifiuta l'intera richiesta, e l'API non scrive nulla. Il messaggio di errore elenca ogni voce che ha fallito, così puoi correggere un batch in una sola volta.

Una richiesta riuscita restituisce 201 Created con { "created": true }, indipendentemente dal fatto che la richiesta abbia effettivamente aggiunto nuove adesioni.

Cambia Ruoli dei Membri

• Endpoint: PATCH https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships
• Intestazioni (obbligatorie): X-API-Key: <DEQUE_API_KEY>, Content-Type: application/json, Accept: application/json
• Corpo della richiesta: stessa struttura user_email_role_pairs di Aggiungi Membri al Progetto

Ogni user_email deve appartenere a un membro attuale del progetto. Un progetto deve sempre conservare almeno un admin. L'API rifiuta una richiesta che lascia il progetto senza admin. Un unico membro rimanente che è l'unico admin del progetto non può cambiare il proprio ruolo. Questa è un'operazione batch. Una voce non valida rifiuta l'intera richiesta, e l'API non scrive nulla.

Una richiesta riuscita restituisce 200 OK con { "ok": true }.

Rimuovi Membri del Progetto

• Endpoint: DELETE https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships?user_emails={comma-separated,url-encoded,emails}
• Intestazioni (obbligatorie): X-API-Key: <DEQUE_API_KEY>, Accept: application/json

Passa gli indirizzi email degli utenti da rimuovere come un elenco separato da virgola in un unico parametro di query user_emails, e codifica l'URL del valore. Ad esempio, un + letterale in un indirizzo che non è codificato arriva come uno spazio e viene rifiutato come malformato. Non c'è un corpo della richiesta. Rimuovere un utente che non è un membro ha successo e non rimuove nulla, quindi una richiesta ripetuta non è un errore. Un progetto deve sempre conservare almeno un admin. L'API rifiuta una richiesta che rimuove l'ultimo admin del progetto. Un unico membro rimanente che è l'unico admin del progetto non può rimuovere sé stesso.

Una richiesta riuscita restituisce 200 OK con gli indirizzi che ha rimosso e quelli che non corrispondevano a nessun membro, così puoi distinguere un errore di digitazione da una rimozione completata:

{
  "deleted": true,
  "removed": ["sam@example.com"],
  "unmatched": ["alx@example.com"]
}

Errori di Risposta sull'Adesione al Progetto