Convenzioni delle richieste: intestazioni di contesto, errori, localizzazione

Ogni endpoint /api/v1/* con ambito organizzazione condivide lo stesso contratto di richiesta: un bearer token, due intestazioni di contesto che selezionano l’organizzazione e il team per conto dei quali agisci, corpi JSON (per i caricamenti di file vengono invece usati multipart o tus), un’unica struttura degli errori e la paginazione tramite cursore negli endpoint di elenco. Questa pagina definisce il contratto; le pagine dei singoli domini lo danno per acquisito.

Intestazioni di contesto

Quasi tutto nell’API DUST appartiene a un’organizzazione e, al suo interno, a un team. Puoi scegliere l’organizzazione e il team nel cui contesto agisce una richiesta mediante due intestazioni:

Intestazione	Obbligatoria	Valore
Dust-Ctx-Org-Id	Sì, negli endpoint con ambito organizzazione	UUID dell’organizzazione.
Dust-Ctx-Team-Id	No	UUID del team. Se omesso, viene usato il team radice dell’organizzazione.

curl -fsS "https://apid.dustid.io/api/v1/threads" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -H "Dust-Ctx-Team-Id: $DUST_TEAM_ID"

Grp è la denominazione precedente

Dust-Ctx-Grp-Id è il nome precedente di Dust-Ctx-Team-Id ed è ancora accettato ovunque venga accettata la nuova intestazione (quando vengono inviate entrambe, prevale Dust-Ctx-Team-Id). Anche alcuni codici di errore (GROUP_ID_REQUIRED) e nomi di campo risalgono a prima della ridenominazione da gruppo a team: nel protocollo di comunicazione, interpreta sempre Grp/group come “team”.

Dettagli importanti nella pratica:

• I valori delle intestazioni devono essere UUID; un valore non valido viene rifiutato con 400 INVALID_REQUEST prima dell’esecuzione dell’endpoint.
• Le varianti con prefisso X- (X-Dust-Ctx-Org-Id, X-Dust-Ctx-Team-Id e la coppia precedente) sono accettate come alias.
• Gli endpoint che richiedono il contesto ma non lo ricevono restituiscono i codici di errore ORG_ID_REQUIRED o TEAM_ID_REQUIRED.
• Alcuni endpoint hanno come ambito l’utente e non richiedono alcun contesto: GET /api/v1/me è quello più comune.

Il contesto è un confine di autorizzazione

L’autorizzazione viene valutata per il tuo utente che agisce nel team indicato dalle intestazioni. La stessa chiamata con un diverso Dust-Ctx-Team-Id può restituire risultati differenti: ciò che puoi elencare, leggere e scrivere corrisponde a ciò che quel team può vedere, ossia i propri registri e tutto ciò che è stato condiviso con esso. L’invio di un contesto a cui non appartieni non concede privilegi superiori: le richieste vengono verificate rispetto alle tue appartenenze effettive. Le operazioni su file, cartelle, relazioni, collegamenti alle Schede, importazioni di assiemi, moduli dei certificati, Fabric, suddivisioni, elenchi dei Team connessi, Pagine pubbliche, Design delle pagine pubbliche, attività e directory degli utenti richiedono l’appartenenza attuale al Team selezionato e verificano che esso appartenga all’organizzazione selezionata, sia per le persone sia per gli account di servizio. La cronologia delle Schede richiede inoltre l’autorizzazione a visualizzare la Scheda interessata; la selezione dell’ID di una Scheda non concede l’accesso. Anche la creazione di Schede, inclusa quella in blocco, e di modelli richiede l’appartenenza attuale al Team selezionato. Gli elenchi delle appartenenze riservati agli amministratori dell’organizzazione restano circoscritti all’Organizzazione selezionata. Consulta Team e condivisione.

Localizzazione

L’intestazione facoltativa Dust-Ctx-Locale seleziona la lingua del testo destinato agli utenti e generato dal server, in particolare delle stringhe message degli errori:

Dust-Ctx-Locale: zh-CN

Le impostazioni locali supportate sono de, es, fr, it, ja, pt, en (predefinita) e zh-CN. Quando l’intestazione è assente, il server ricorre prima all’intestazione standard Accept-Language e poi all’inglese. I codici di errore sono identificatori stabili e non vengono mai localizzati: usa code per gestire la logica condizionale e mostra message.

Errori

Le richieste non riuscite restituiscono un corpo JSON con un’unica struttura coerente:

{
  "code": "UNAUTHORIZED",
  "message": "You are not authorized to perform this action",
  "status": 401,
  "detail": { }
}

Campo	Tipo	Significato
code	string	Codice di errore stabile e leggibile dalla macchina. Usalo per gestire la logica condizionale.
message	string	Descrizione leggibile dall’utente, localizzata in base a Dust-Ctx-Locale.
status	number	Corrisponde al codice di stato HTTP.
detail	object (facoltativo)	Contesto aggiuntivo relativo all’errore, ad esempio i dettagli della convalida.

Codici che incontrerai fin dalle prime fasi:

Codice	Stato tipico	Quando si verifica
INVALID_REQUEST	400	Corpo, query o intestazione non validi (dettagli della convalida in detail).
UNAUTHORIZED	401	Bearer token mancante, scaduto o non valido.
FORBIDDEN	403	L’utente è autenticato, ma non può eseguire l’operazione nel contesto di questo team.
NOT_FOUND / NO_DATA_FOUND	404	Nessun registro corrispondente è visibile in questo contesto.
ORG_ID_REQUIRED / TEAM_ID_REQUIRED	400	Intestazione di contesto mancante in un endpoint con ambito specifico.
THREAD_DATA_CONFLICT	409	Conflitto di concorrenza ottimistica: la tua vista della scheda non era aggiornata.

Ogni risposta contiene inoltre un’intestazione x-request-id. Registrala nei log e includila quando contatti l’assistenza: consente di individuare con precisione la tua richiesta nelle tracce del server.

Errori ed esiti delle scansioni è il riferimento completo: include tutti i codici che probabilmente incontrerai con i relativi stati, le tabelle canoniche degli esiti di identificazione e verifica, le indicazioni sui nuovi tentativi e le istruzioni per conservare una ricevuta di scansione quando un’operazione non riesce.

Un risultato negativo è comunque una risposta

Gli endpoint di scansione comunicano gli esiti mediante codici di errore. Un’identificazione che non trova nulla restituisce 404 IDENTIFIER_NOT_FOUND: questa è la risposta, non un errore di trasporto. Una ricerca incompleta restituisce 503 SCAN_SEARCH_INCOMPLETE, che indica una situazione diversa. Usa code per gestire la logica condizionale; consulta la tabella degli esiti canonici di identificazione.

Paginazione

Gli endpoint di elenco (schede, cartelle, file, eventi, modelli, …) utilizzano la paginazione tramite cursore:

• Richiesta: parametri di query pageSize (lunghezza della pagina) e cursor (stringa opaca proveniente da una pagina precedente). pageSize deve essere un numero intero compreso tra 1 e 1.000; alcuni endpoint impongono un valore massimo inferiore. Omettilo per usare il valore predefinito dell’endpoint.
• Gli endpoint che utilizzano pageIndex accettano numeri interi compresi tra 0 e 1.000.000. I valori di paginazione negativi o frazionari vengono rifiutati.
• Risposta: l’array degli elementi più le stringhe facoltative dei cursori next e prev. L’assenza di next indica che ti trovi nell’ultima pagina.

# First page
curl -fsS "https://apid.dustid.io/api/v1/threads?pageSize=50" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID"

# Follow the cursor
curl -fsS "https://apid.dustid.io/api/v1/threads?pageSize=50&cursor=$NEXT" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID"

{
  "threads": [ ... ],
  "next": "eyJjcmVhdGVkQXQiOi...",
  "prev": "eyJjcmVhdGVkQXQiOi..."
}

I cursori sono opachi: conservali e riutilizzali senza mai analizzarli. Gli endpoint di elenco che supportano l’ordinamento accettano order (asc/desc) e un orderCol specifico dell’endpoint (per le schede: createdAt, updatedAt, name).

Livelli di autorizzazione

Ogni operazione richiede uno di tre livelli di privilegio e il prefisso del percorso indica quale, ancora prima di leggere lo schema:

Prefisso	Chi può effettuare la chiamata	Note
/api/v1/org/*	Amministratori dell’organizzazione: utenti con il ruolo admin (o owner) nell’Organizzazione indicata da Dust-Ctx-Org-Id	Creazione dei team, aggiornamenti dei team, appartenenze
/api/v1/connections/*	Amministratori del Team: amministratori del Team operativo indicato da Dust-Ctx-Team-Id	Ciclo di vita e modifiche delle connessioni
tutto il resto	Membri del contesto della richiesta, salvo diversa indicazione dell’operazione	Funzionalità standard

Ogni operazione contiene inoltre un’estensione x-required-role nella specifica OpenAPI (member, publisher, team-admin o org-admin): considerala la fonte autorevole dei criteri applicabili alla singola operazione; un’operazione priva dell’annotazione richiede member. publisher è un’autorizzazione concessa nell’ambito dell’appartenenza a un Team, non un livello a sé stante: è necessaria per rendere pubblicamente leggibili i dati di un Team e gli amministratori del Team la possiedono sempre. La chiamata di un’operazione superiore al tuo livello restituisce 403 FORBIDDEN indipendentemente dal payload.

Corpi, ID e timestamp

• Le richieste utilizzano Content-Type: application/json, salvo quando un endpoint accetta esplicitamente dati di moduli multipart (scansioni degli identificatori in /api/v1/tags/*, caricamenti di file).
• Gli ID sono stringhe UUID conformi a RFC 4122 (threadId, eventId, ID dell’organizzazione e del team, …). Trattali come valori opachi.
• I timestamp (createdAt, updatedAt, archivedAt, …) sono stringhe di data e ora in UTC.
• Le scritture sono basate su eventi: la modifica di una scheda aggiunge un evento alla sua cronologia anziché sovrascriverla implicitamente; le letture come GET /api/v1/threads/{thread_id} restituiscono { thread, events }.

Vedi anche

• Guida introduttiva all’API — queste convenzioni in un unico flusso funzionante.
• Errori ed esiti delle scansioni — tutti i codici, le tabelle degli esiti di identificazione/verifica e le indicazioni sui nuovi tentativi.
• Autenticazione e chiavi API — origine del bearer token.
• Modello principale — significato di schede, team e identificatori.
• Riferimento completo dell’API — parametri e schemi per ogni endpoint, generati dalla specifica attuale.