Un ecosistema di domini · e un portale di API
Tutto quello che il pannello sa fare — cercare, elencare, scaricare, ricomporre, riprodurre, guardare come sta la macchina — il nodo lo sa fare anche su richiesta di un altro programma. Non c'è una versione ridotta per gli ospiti: è la stessa identica porta da cui entra il pannello.
Il Portico è il posto dove queste porte si guardano una per una. Ogni esempio qui dentro viene eseguito davvero, contro questo nodo, nel momento in cui premi il tasto. Niente risposte finte, niente schermate registrate.
Se hai già chiaro cosa sono, salta pure al ricettario. Se invece la parola ti dice poco, questa è la spiegazione più corta che sono riuscito a scrivere.
Quando apri il pannello di XFS Bot e clicchi su «Archivio», il browser non fa nulla di misterioso: manda al nodo una richiesta che, tradotta in italiano, dice «dammi l'elenco delle cartelle». Il nodo risponde con un pacchetto di testo, e il pannello lo disegna a schermo.
Le API sono esattamente quella richiesta, senza il pannello intorno. Sono l'elenco delle domande che il nodo sa capire e delle risposte che sa dare. Il pannello è solo uno dei programmi che le usano: il tuo sito, uno script, un'app, un foglio di calcolo possono usare le stesse.
Non c'è una «API pubblica ridotta» e una «vera» riservata al pannello. È la stessa. Il pannello non ha nessun canale privilegiato: se una cosa la fa lui, la puoi fare anche tu.
GET /api/v1/fm/folders
{ "folders": [ … ] }
La chiave è tutta la faccenda. Ogni richiesta porta con sé una
X-API-Key. Quella chiave è intestata a una persona, e il nodo risponde
con quello che quella persona vedrebbe entrando dal pannello: né di più
né di meno. Non c'è una chiave che «vede tutto».
A seconda di quanto hai voglia di scrivere codice, ci sono tre strade. Tutte e tre funzionano da qualunque sito: non serve che il tuo dominio faccia parte della federazione.
Una riga di <script> con la tua chiave e il nome del riquadro.
Il nodo ti manda un pezzo di interfaccia già fatto — con la barra di
avanzamento, il tasto per annullare, tutto — e tu non scrivi una riga di
JavaScript.
Vuoi il tuo stile, il tuo testo, la tua grafica? Una fetch() di cinque
righe e il bottone è tuo. Il nodo fa il lavoro, tu decidi come si vede.
Niente browser: curl, PowerShell, Python, un cron notturno.
Le stesse chiamate, dalla riga di comando. Utile per gli automatismi,
i backup, i controlli.
Questa non ha nemmeno bisogno di una chiave: la carta d'identità di un dominio è pubblica per scelta, perché chi deve decidere se fidarsi deve poter guardare senza chiedere il permesso.
Se hai premuto «Provalo adesso», hai appena usato un'API. Davvero: quello che è comparso nel riquadro verde è la risposta di questo nodo, arrivata mentre leggevi. Il resto del Portico è la stessa cosa, ripetuta su tutte le porte che il nodo tiene aperte.
Non è un elenco di funzioni: sono cose che qualcuno ha effettivamente voluto fare, e il modo in cui si fanno.
Un elenco di cartelle e file, con pesi e date, dentro una pagina qualunque. L'archivio resta dov'è: la pagina si limita a chiederne l'indice.
Un collegamento incollato in un forum diventa un tasto: il nodo se lo tira giù, lo ricompone se era in pezzi, e restituisce un collegamento diretto per il browser.
Una casella sola che guarda nel proprio archivio, negli archivi dei domini vicini e nelle fonti esterne, e mette insieme i risultati.
Il nodo apre un flusso con i salti
(Range) e, se serve, riconverte al volo. Un
<video src> e hai finito.
Memoria, processore, code, spazio. Utile per una pagina di stato o per un cruscotto fatto in casa.
Chi c'è, di chi si fida, cosa ha deciso e perché. Tutto senza credenziali: è il punto dell'intesa.
No. E vale la pena spiegare bene perché, perché è la cosa che si capisce peggio.
Chi fa parte dell'ecosistema è il nodo, non il sito. Nel momento in cui hai un dominio con XFS Bot sopra, sei dentro: hai un archivio, degli utenti, delle stanze, e delle chiavi da distribuire. Le chiavi le generi tu, dal tuo pannello, e sono tue.
Il sito che usa quella chiave può essere qualunque cosa. Un blog su WordPress, un forum vecchio di vent'anni, una pagina statica su una chiavetta, un foglio HTML aperto dal desktop. Non deve chiedere il permesso a nessuno, non deve registrarsi da nessuna parte, non deve parlare la lingua della federazione. Deve solo mandare la tua chiave.
In altre parole: la chiave è il pezzo di ecosistema che porti con te. Dove la incolli, lì arriva il tuo dominio.
C'è un solo passaggio da non dimenticare. Quando la chiamata parte da un browser, e la pagina sta su un dominio diverso da quello del nodo, il browser chiede al nodo il permesso di leggere la risposta. Quel permesso è l'elenco dei domini autorizzati della chiave: se il tuo sito non c'è scritto, la chiamata parte ma la risposta il browser te la nasconde.
Si aggiunge dal pannello, alla scheda API, in dieci secondi. Da riga di comando (curl, PowerShell, un programma sul server) il problema non esiste proprio: quel controllo è una cosa del browser.
Questa è la parte che conviene aver chiara prima di distribuire chiavi in giro.
Ogni chiave nasce dentro il pannello di una persona e resta sua. Quando arriva una richiesta, il nodo guarda di chi è la chiave e risponde come risponderebbe a lei.
Se Marisa, che non è amministratrice, genera una chiave e la mette sul suo sito, quel sito mostrerà le cartelle di Marisa. Non quelle dell'amministratore, non quelle di Gigi. Le sue.
Una chiave incollata in una pagina web è pubblica per costruzione: chiunque apra il sorgente la vede. Per questo esiste la casella «sola lettura».
Una chiave così
legge tutto quello che il suo proprietario potrebbe leggere e non scrive niente:
ogni POST, PUT e DELETE riceve un
403. Anche da riga di comando. Anche a chi l'ha rubata.
La chiave che fa funzionare questo Portico è proprio una di quelle.
È scritta in chiaro dentro /portico/assets/portico.js e la puoi
leggere adesso. Non c'è niente da nascondere: non può far partire uno
scarico, non può cancellare una cartella, non può toccare un account.
Nel ricettario ci sono anche gli esempi che
scrivono: premi «Provalo» e vedrai il 403 con i tuoi occhi.
È il modo più onesto di far vedere che il freno c'è.
Il Portico serve a far vedere. È una vetrina didattica, e come tutte le vetrine ha il vetro davanti:
| Qui dentro | Sul tuo sito, con la tua chiave |
|---|---|
| Si legge tutto: elenchi, cartelle, ricerche, stato, federazione. | Uguale. |
Non parte nessuno scarico. La chiave del Portico è in sola lettura e il
nodo risponde 403. |
Parte davvero. La tua chiave piena fa tutto quello che faresti dal pannello. |
Non si cancella niente. Gli esempi con DELETE ci sono, e mostrano
il rifiuto. |
Cancella davvero. Con la stessa cura con cui lo faresti a mano. |
| Nessun account, nessuna impostazione, nessun utente viene toccato. | Se sei amministratore, sì. |
Il motivo è banale: se da questa pagina si potesse far partire uno scarico, qualcuno lo farebbe partire mille volte e la banda del nodo finirebbe in un pomeriggio. Sul tuo nodo, con la tua chiave, il problema non esiste: è casa tua.