Come funziona Omniscol — una sola API, un'unica fonte di verità

Alcuni aspetti su come è costruito Omniscol meritano di essere conosciuti prima di integrarlo: spiegano perché l'API è così completa, come l'interfaccia si adatta a ogni utente, e un punto di riservatezza da tenere presente.

Una sola applicazione su una sola API

Omniscol funziona come un'unica applicazione web nel suo browser. Ogni schermata, pulsante e tabella viene disegnato chiamando l'API pubblica di Omniscol — la stessa API che Lei può chiamare — documentata nel riferimento API interattivo di Omniscol, la pagina Sviluppatori (omniscol.com/it/developers). Non esiste un'API nascosta, «reale», dietro quella che Lei integra: ciò che l'interfaccia usa è ciò che Lei ottiene. Alcune operazioni vanno nella direzione opposta — offerte per l'integrazione ma non utilizzate dall'applicazione stessa —: per esempio, i punti di accesso di ricerca avanzata e risoluzione di entità (pensati per un agente IA tramite MCP), o quelli che permettono a un sistema esterno di alimentare Omniscol (un ETL che mantiene sincronizzato un database esterno).

operationId — una chiave, un'unica fonte di verità

Ogni operazione è una coppia metodo + URL (per esempio GET /api/schedules/lessons/{datesrange}), e ciascuna porta un identificatore stabile: il suo operationId (qui os_schedules_dates_get). Il nome è strutturato: os (Omniscol), poi il modulo (schedules), poi ciò su cui agisce l'operazione (dates — a volte più segmenti uniti da trattini) e sempre il metodo HTTP per ultimo (get, post, put, delete). È questa chiave unica che Omniscol usa ovunque — per nominare l'operazione sulla pagina Sviluppatori, per costruire lo strumento MCP corrispondente e per designarla da una personalizzazione dell'API o da questa guida. Definita una sola volta, mantiene sincronizzate tutte le superfici: la documentazione, gli strumenti e l'interfaccia non possono divergere, poiché leggono tutti la stessa definizione.

L'interfaccia segue i suoi diritti

Un elemento grafico dotato di un'azione — un pulsante, una scheda, una voce di menu — appare solo quando l'operazione che lo sostiene le è accessibile. Ciò dipende dal suo ruolo e dai suoi ruoli personalizzati (vedere Utenti e ruoli), dalla sua offerta e dalle sue opzioni (vedere Piani e opzioni di Omniscol). Modifichi uno di questi elementi e l'interfaccia si ricompone: elementi, e persino interi moduli, appaiono o scompaiono di conseguenza.

Lo stesso principio agisce oltre i suoi diritti personali. Il reparto informatico può disattivare alcune operazioni tramite una personalizzazione dell'API, e gli elementi corrispondenti scompaiono dall'interfaccia (vedere Personalizzazione dell'API). Lo stesso vale quando un dato è mantenuto aggiornato da una sincronizzazione esterna: la sua creazione e la sua modifica locali possono essere disattivate, e i relativi comandi cedono allora il posto alla sincronizzazione (vedere Sincronizzazione con sistemi esterni).

Ecco perché Omniscol non ha alcun portale separato per gli studenti o gli insegnanti. C'è una sola applicazione; ogni persona vede l'interfaccia sincronizzata con i propri diritti — uno studente, un insegnante, un amministratore e il titolare di un ruolo personalizzato ottengono esattamente le operazioni a cui hanno diritto, e nient'altro.

L'interfaccia è una comodità, non il lucchetto

Poiché l'interfaccia è guidata dai suoi diritti, si potrebbe essere tentati di considerare un pulsante nascosto come un confine di sicurezza. Non lo è. Ogni chiamata viene riverificata sul server rispetto alla sua identità e ai suoi diritti; un'operazione a cui non ha diritto viene lì rifiutata, qualunque cosa l'interfaccia mostri. L'interfaccia si adatta per chiarezza e comodità; il confine reale è applicato lato server, a ogni richiesta.

Token e link di condivisione, lo stesso modello

Un token API o un link di condivisione è limitato a un insieme di operazioni: quelle che Lei autorizza al momento della creazione. Il server applica questa restrizione a ogni chiamata, esattamente come per un utente connesso. Un link di condivisione, un token e una persona nell'interfaccia sono tre modi di raggiungere la stessa API controllata dai diritti — mai una porta di servizio che la aggira.

Attraversare un'interruzione di connessione

Poiché ogni schermata legge l'API, Omniscol può anche conservare nel suo browser le risposte già ricevute, affinché una breve perdita di rete non interrompa la sua lettura. Questa copia locale risiede nel suo database (IndexedDB), accanto alla normale cache di pagine del browser. È una cache di lettura: se la connessione cade, continua a vedere ciò che aveva già aperto. Non mette le sue modifiche in coda e non le riproduce — una modifica passa sempre dal server.

Questa copia locale si basa sul suo consenso. La prima volta su un browser, Omniscol le chiede se si fida di esso; la copia inizia una volta che ha accettato. La voce Cache offline del menu utente la attiva o la cancella in seguito in qualsiasi momento — un segno di spunta indica che è attiva.

Due cose da sapere:

• I dati personali ne sono esclusi. Vengono conservate solo le letture riuscite; le risposte che il server contrassegna come non memorizzabili (dati di sessione e di autenticazione) non vengono mai messe in cache, e da ciò che viene messo in cache il software rimuove i dati di contatto delle persone — e-mail, telefono, data di nascita, login, numero di identificazione, stato della password — ed elimina completamente gli account amministratore. La copia locale contiene i normali dati di lavoro, non l'elenco nominativo.
• Su una postazione condivisa, preferisca una finestra di navigazione privata (incognito). La disconnessione non cancella questa copia locale (né la normale cache del browser); una finestra privata elimina entrambe alla chiusura. È la cura che merita qualsiasi applicazione web su una macchina che non controlla.