Usare bene l'API: cache, webhook e limiti di frequenza
PremiumUn'integrazione che interroga Omniscol ogni minuto per verificare se i dati sono cambiati riceve, nella maggior parte dei casi, la stessa risposta della chiamata precedente. Consuma inutilmente la propria quota e sollecita il server senza ottenere alcuna informazione nuova.
Questa pagina presenta i meccanismi che permettono di evitare queste chiamate superflue e i limiti di frequenza applicabili all'API.
Evitare di recuperare i dati invariati
La maggior parte delle risposte di lettura dell'API contiene un'intestazione
ETag, che identifica una versione della risposta. Conservi questo
identificativo insieme ai dati ricevuti e lo trasmetta alla chiamata
successiva nell'intestazione If-None-Match:
curl -i -G "https://il-suo-istituto.omniscol.com/api/schedules/lessons/20261102-20261108" \
-H "Authorization: Bearer $TOKEN" \
-H 'If-None-Match: W/"os1.…"'
Se i dati non sono cambiati, Omniscol risponde 304 Not Modified, senza
corpo della risposta. Può quindi riutilizzare i dati conservati in cache. In
caso contrario riceve una risposta 200 OK completa, accompagnata da un nuovo
ETag.
L'ETag è un valore opaco: lo conservi e lo rinvii identico, virgolette e
prefisso W/ compresi, senza cercare di costruirlo né di decodificarlo. È
specifico della richiesta che lo ha prodotto e dell'accesso utilizzato: non lo
riutilizzi per un altro URL né con un altro token.
L'intestazione Cache-Control: private, no-cache precisa che la risposta può
essere conservata in una cache privata, ma che deve essere riconvalidata
presso Omniscol prima di essere riutilizzata. È esattamente il ruolo di
If-None-Match.
Alcune risposte non contengono un ETag, in particolare quando dipendono dalla data odierna e possono cambiare senza che i dati dell'account vengano modificati. Queste risposte devono essere recuperate di nuovo a ogni chiamata.
Dopo il rilascio di una nuova versione di Omniscol, gli ETag vengono
rinnovati, anche se i dati non sono cambiati. La prima chiamata riceve allora
una risposta 200, poi le chiamate successive possono di nuovo beneficiare
delle risposte 304.
Il 304 riduce anche l'elaborazione lato server. Nella maggior parte dei
casi, quando nessun dato dell'account è cambiato dall'ultima chiamata,
Omniscol può rispondere senza nemmeno rileggere i dati interessati, e questo
304 non viene conteggiato nella quota associata alla sua chiave API. Un
304 ottenuto dopo la rilettura dei dati, invece, viene conteggiato come una
risposta ordinaria.
La riconvalida regolare resta quindi poco costosa quando i dati sono invariati. Rimane tuttavia soggetta al limite generale per indirizzo IP.
Conservare le risposte in cache
Se più utenti o più schermate della sua applicazione consultano gli stessi dati, è inutile interrogare Omniscol per ciascuno di essi.
Conservi le risposte e i relativi ETag in una cache applicativa sotto il suo
controllo, per esempio Redis, Memcached o una tabella di database. La sua
applicazione può allora servire i dati da questa cache, che si occupa di
riconvalidarli presso Omniscol con If-None-Match, a intervalli regolari o
quando un webhook segnala una modifica.
La chiave della cache deve tenere conto dell'URL completo, del token di
autenticazione utilizzato e, quando se ne serve, del corpo della richiesta
GET e delle intestazioni che fanno variare la risposta, come
Accept-Language. Due token con diritti diversi possono dare accesso
a dati diversi: una risposta ottenuta con uno non deve mai essere servita a un
utente i cui diritti non consentono di accedervi.
Conservi inoltre il corpo di ogni risposta insieme al suo ETag. Senza i dati
corrispondenti, una risposta 304 non permette di ricostruire il risultato
atteso.
Questa cache applicativa è distinta da una cache HTTP condivisa: la direttiva
Cache-Control: private vieta a quest'ultima di memorizzare le risposte.
Ricevere notifiche invece di interrogare regolarmente
Invece di verificare periodicamente se i dati sono cambiati, può chiedere a Omniscol di notificare la sua applicazione quando avviene una modifica.
Questo meccanismo si basa sui webhook, configurabili nella schermata di personalizzazione dell'API (vedere Personalizzazione dell'API). Un webhook può sorvegliare un endpoint preciso oppure un evento che raggruppa più modifiche, come la modifica di un orario.
Invalidare la cache alla ricezione di un webhook
L'uso più semplice consiste nel trattare il webhook come un segnale di invalidazione.
Quando arriva una notifica, la sua applicazione segna i dati interessati come scaduti e li riconvalida presso Omniscol. Non è necessario interpretare il contenuto della modifica: il webhook indica semplicemente che è necessaria una nuova verifica.
Questo funzionamento si combina naturalmente con la cache descritta in precedenza.
Sincronizzare le lezioni tramite differenze
Se mantiene una copia sincronizzata delle lezioni, l'opzione Con dati dell'evento di modifica dell'orario permette di ricevere un differenziale contenente le lezioni aggiunte, modificate ed eliminate.
La sua applicazione può allora applicare soltanto queste modifiche, senza recuperare di nuovo l'intero orario.
Garantire la ricezione delle notifiche
Omniscol effettua un solo tentativo di invio per ogni webhook. Attende al massimo quattro secondi, non riprova in caso di errore e lo registra nei propri log.
Il suo server deve quindi confermare la ricezione rapidamente, con una
risposta 200 OK o 202 Accepted, ed eseguire poi l'elaborazione necessaria
in modo asincrono.
Mantenga inoltre una riconvalida periodica come meccanismo di recupero. Se il
suo server non era disponibile al momento dell'invio di un webhook, questa
verifica permetterà di rilevare le modifiche mancate. Grazie alle risposte
304, resta poco costosa quando i dati sono aggiornati.
Proteggere i webhook
Per verificare che una notifica provenga davvero da Omniscol, configuri un'intestazione HTTP personalizzata contenente un segreto noto soltanto alla sua applicazione e a Omniscol. Il suo server deve rifiutare le chiamate che non presentano il valore atteso.
Due intestazioni supplementari forniscono informazioni sul contesto della notifica:
X-Schoolidentifica l'account Omniscol interessato;X-OS-authcontiene il token di autenticazione dell'utente all'origine della modifica.
Il token trasmesso in X-OS-auth è riservato. Non lo registri nei suoi log,
non lo trasmetta ad altri servizi e ne limiti rigorosamente l'accesso.
Richiedere soltanto i dati necessari
Una risposta che contiene meno dati è in genere più rapida da produrre, da trasferire e da mettere in cache.
Per le lezioni, limiti il periodo richiesto e filtri i risultati sulle entità che le interessano (vedere API delle lezioni).
Per le ricerche, l'endpoint search/query offre filtri, proiezione dei campi
e paginazione (vedere Interrogazione avanzata).
Per aggiornare un gran numero di elementi dello stesso tipo (classi, aule, materie e così via), preferisca gli endpoint che permettono di trasmettere un'intera raccolta in una sola richiesta, quando sono disponibili nella documentazione OpenAPI, piuttosto che moltiplicare le chiamate singole.
Rispettare i limiti di frequenza
All'API si applicano due limiti di frequenza. Quando un limite viene
raggiunto, Omniscol risponde 429 Too Many Requests, accompagnato da
un'intestazione Retry-After che indica il numero di secondi da attendere
prima di ripetere la richiesta.
Limite per indirizzo IP
Il limite generale è di 300 richieste per finestra di 10 secondi, per tutti gli endpoint dell'API, compresi MCP e i pannelli informativi.
Questa soglia è in genere sufficiente per un'integrazione progettata correttamente. Può tuttavia essere raggiunta da cicli di chiamate senza temporizzazione o da un numero eccessivo di richieste parallele.
Limite per chiave API
I token derivati da una stessa chiave API condividono due quote:
- 60 richieste al minuto;
- 5.000 richieste al giorno.
Le risposte possono contenere le intestazioni seguenti, che permettono di seguire il consumo:
RateLimit-Policyindica le quote applicabili, per esempio60;w=60, 5000;w=86400;RateLimit-Limitindica la quota corrispondente al limite più vicino a essere raggiunto;RateLimit-Remainingindica il numero di richieste ancora disponibili per questa quota;RateLimit-Resetindica il numero di secondi prima del suo rinnovo.
Queste intestazioni sono in particolare assenti dalle risposte 304 ottenute
senza rilettura dei dati: la loro assenza non significa che la quota sia
esaurita.
Quando la quota è esaurita, la risposta 429 indica anche il tempo di attesa
nel proprio corpo, tramite il campo retry_after.
Le risposte 304 ottenute senza rilettura dei dati non vengono conteggiate in
queste quote, ma restano soggette al limite generale per indirizzo IP.
Se questi limiti ostacolano un uso legittimo dell'API, ci contatti invece di moltiplicare le chiavi.
Gestire gli errori e i nuovi tentativi
Dopo una risposta 429
Rispetti il tempo indicato da Retry-After prima di ripetere la richiesta.
Riprovare subito è inutile e può prolungare la situazione, in particolare se
più processi della sua applicazione effettuano contemporaneamente nuovi
tentativi.
Dopo un errore del server o un timeout
Dopo un errore 5xx o un superamento del tempo di attesa, una richiesta di
lettura può essere ripetuta con un intervallo crescente tra i tentativi: un
secondo, poi due, poi quattro, per esempio, fino a un numero massimo di
tentativi.
Per una richiesta di scrittura la situazione è diversa: la modifica può essere stata registrata anche se la risposta non le è mai arrivata. Verifichi lo stato reale dei dati prima di ripetere l'operazione, per evitare modifiche duplicate.
Dopo una risposta 401
Una risposta 401 Unauthorized non può in genere essere risolta con un nuovo
tentativo con lo stesso token. Può indicare in particolare che il token è
scaduto, che la sua chiave API è stata eliminata o è scaduta, oppure che
l'endpoint richiesto non fa parte di quelli che essa autorizza.
Verifichi il token e le autorizzazioni associate prima di ripetere la chiamata (vedere API Omniscol).