Guida rapida all’API REST di archiviazione cloud

Usa l’API REST di archiviazione cloud su https://api.dosya.dev/api per elencare gli spazi di lavoro, scegliere una destinazione e leggerne i file. Questa guida invia richieste di lettura autenticate senza modificare i file salvati. L’API usa /api; non aggiungere /v1 o /v2.

Crea la credenziale di prova

1. Accedi a Profilo → Chiavi API e scegli Crea una chiave API.
2. Inserisci un nome riconoscibile in A cosa serve? e scegli Solo lettura in Cosa può fare?.
3. Espandi Restrizioni e scadenza. In Protocolli, scegli Solo quelli che scelgo e spunta API REST. Scegli Spazio di lavoro se l’integrazione deve accedere a un solo spazio di lavoro. Lascia Cartella non impostato: le chiavi ordinarie ancorate a cartelle sono rifiutate su REST.
4. Scegli Scade tra 30 giorni, controlla il riepilogo e scegli Genera la chiave. Copia il token completo dos_ dalla finestra che conferma la creazione prima di scegliere Fatto; l’elenco delle chiavi non può mostrarlo di nuovo.

Un account gratuito può avere tre chiavi API; il limite dell’account sugli altri piani è 20. Le chiavi scadute esistenti contano ancora. I permessi della chiave restringono l’accesso dell’account; non concedono appartenenza a uno spazio di lavoro né permessi di ruolo mancanti.

Passaggi: invia la prima richiesta

Per gli esempi servono una shell, curl e Python 3. Imposta DOSYA_API_KEY tramite il gestore di segreti o una richiesta interattiva; non sostituire mai la variabile con un token reale in un comando salvato. Ecco un’opzione interattiva per Bash:

read -r -s -p 'API key: ' DOSYA_API_KEY
printf '\n'
export DOSYA_API_KEY
curl --fail-with-body --silent --show-error \
  'https://api.dosya.dev/api/workspaces' \
  -H "Authorization: Bearer $DOSYA_API_KEY" \
  -o workspaces.json
python3 -c 'import json; d=json.load(open("workspaces.json")); print([(w["id"],w["name"]) for w in d["workspaces"]])'

Una richiesta riuscita restituisce HTTP 200 con ok: true e un array workspaces. Usa un ID dello spazio di lavoro restituito, non il nome visualizzato. Una chiave vincolata a uno spazio di lavoro vede solo quello. Un array vuoto non dimostra che l’account non abbia spazi di lavoro: controlla l’ambito della chiave e la tua appartenenza attuale.

Leggi i file dalla cartella radice di uno spazio di lavoro:

DOSYA_WORKSPACE_ID='REPLACE_WITH_RETURNED_WORKSPACE_ID'
curl --fail-with-body --silent --show-error --get \
  'https://api.dosya.dev/api/files' \
  -H "Authorization: Bearer $DOSYA_API_KEY" \
  --data-urlencode "workspace_id=$DOSYA_WORKSPACE_ID" \
  --data-urlencode 'page=1' --data-urlencode 'per_page=100' \
  -o files.json
python3 -m json.tool files.json

L’elenco dei file usa 100 elementi per pagina per impostazione predefinita e accetta per_page da 10 a 500. Specifica folder_id per elencare una sottocartella nota. Gli ID file restituiti sono usati dalle route di metadati e download. Il ruolo nello spazio di lavoro deve consentire la pagina File; contenuti nascosti e limitazioni alle cartelle possono restringere l’elenco.

Controlla gli errori prima di aggiungere scritture

Risposta	Cosa cambiare
401, Invalid or expired API key	Usa il token completo, controlla scadenza e revoca e mantieni esatta l’intestazione Authorization: Bearer ….
403, This API key is not permitted to use the api surface	Includi API REST nella selezione dei protocolli della credenziale.
403, This API key is anchored at a folder and can only be used over WebDAV or the S3 gateway	Genera una chiave REST vincolata allo spazio di lavoro senza ancoraggio a una cartella.
403, This API key is restricted to specific source addresses	Invia da un indirizzo consentito; non falsificare le intestazioni di inoltro.
403, This API key is being used outside its allowed hours	Controlla fuso orario, giorni e intervallo settimanale selezionati.
429 con Retry-After	Attendi i secondi indicati e riduci le richieste simultanee invece di riprovare continuamente.
503, Service temporarily unavailable	Conserva la credenziale e riprova dopo i cinque secondi indicati. Questo errore nella ricerca di autenticazione non richiede di sostituire la chiave.

Dopo l’autenticazione vengono controllati protocollo, indirizzo e orario, ancoraggio alla cartella, ambito e vincolo allo spazio di lavoro prima di addebitare il contatore delle richieste della chiave. Una chiave Solo lettura può elencare e scaricare; una scrittura viene rifiutata con un messaggio che indica ambito, metodo e percorso. Non provare questo limite su dati importanti con una chiave ad accesso completo.

Lo stato HTTP e il campo JSON error identificano un errore. Molte risposte JSON includono ok, ma l’indirizzo del servizio per gli URL di download restituisce url, size, name e region senza il campo ok; verifica la risposta effettiva anziché presumere una forma universale. Conserva stato, errore ed eventuale identificatore della richiesta, oscurando l’intestazione di autorizzazione.

Risultato previsto e pulizia sicura

Confronta gli ID degli spazi di lavoro e i nomi dei file restituiti con l’app connessa. L’elenco non carica, elimina o crea link di condivisione e nessun destinatario riceve file da queste richieste. Conserva solo i metadati che sei autorizzato a mantenere.

Torna a Profilo → Chiavi API, espandi la chiave di prova, scegli Revoca e conferma di nuovo Revoca al termine. La revoca non può essere annullata; le integrazioni che usano quella credenziale non si autenticano più. Creare, elencare ed eliminare chiavi per ID richiede una sessione autenticata, quindi una chiave bearer non può creare o amministrare altre chiavi. In produzione usa credenziali separate per lettura, caricamento e amministrazione e verifica gli esiti incerti delle scritture prima di ripetere una richiesta.

Guide correlate

• Creare e gestire chiavi API
• Caricare byte e riprendere trasferimenti multipart
• Scaricare tramite un URL firmato temporaneo
• Registrare e verificare un ricevitore webhook