L'albero delle cartelle

Il caso più richiesto

L'albero delle cartelle, ramo per ramo

«Vorrei mettere sul mio sito l'elenco di alcune cartelle dell'archivio». È la domanda che fanno tutti, e la risposta sta in due chiamate. Questa pagina le fa davvero, davanti a te, e ti mostra ogni richiesta che parte.

👁

Le cartelle qui sotto sono quelle vere di chi possiede la chiave del Portico. Se generassi una chiave tua e sostituissi solo quella, questa identica pagina mostrerebbe le tue. Non c'è altro da cambiare: né l'indirizzo, né il codice.

Sotto il cofano

Come è fatto, per intero

Non c'è una libreria, non c'è un motore. C'è questo.

1 · Chiedi tutte le cartelle, una volta sola

La risposta contiene id, name e parent_id di ognuna. Con quei tre campi l'albero te lo costruisci in memoria: non serve una chiamata per ogni ramo.

const r = await fetch("/api/v1/fm/folders", {
  headers: { "X-API-Key": "LA_TUA_CHIAVE" }
});
const { folders } = await r.json();

// figli[id della madre] = [ cartelle ]
const figli = {};
for (const f of folders) {
  (figli[f.parent_id || 0] ??= []).push(f);
}
// figli[0] sono le cartelle di primo livello

2 · Quando qualcuno apre un ramo, chiedi i suoi file

I file sono tanti e non servono finché il ramo resta chiuso. Si chiedono al momento, con folder_id.

const r = await fetch("/api/v1/fm/files?folder_id=" + id + "&limit=200", {
  headers: { "X-API-Key": "LA_TUA_CHIAVE" }
});
const { files } = await r.json();
// ogni file ha filename, filesize, created_at, source

3 · Se preferisci, un ramo intero in un colpo

C'è anche la scorciatoia: cartelle e file di un sottoalbero, già annidati, con una chiamata sola. Comoda quando devi disegnare tutto subito.

GET /api/v1/fm/folders/<id>/tree

🚧

Sul tuo sito serve un passaggio in più. Questa pagina è servita dallo stesso dominio del nodo, quindi il browser non fa domande. Se la stessa pagina stesse su https://iltuosito.it, dovresti aggiungere quell'origine ai domini autorizzati della chiave, dal pannello, scheda API. Da curl o da un programma sul server il problema non si pone.

Lo stesso mattone, altre forme

Cosa altro puoi farci

🔗 Una cartella condivisibile

GET /fm/folders/<id>/download-token restituisce un gettone a tempo. Con quello, /fm/folders/<id>/archive.zip?token=… si scarica senza chiave. Da mandare a qualcuno che non deve avere accesso ad altro.

🌊 Una cartella come torrent

GET /fm/folders/<id>/torrent costruisce al volo un torrent multi-file con il nodo stesso come sorgente web. Un client qualunque lo scarica a pezzi e in parallelo.

💾 Una cartella come disco di rete

POST /fm/network-share la pubblica via WebDAV: si monta come un disco in Esplora risorse. L'elenco di quelle attive si legge con GET /fm/network-shares.