Usare bene l'API: cache, webhook e limiti di frequenza

Premium

Ottimizzare le chiamate all'API Omniscol: usare gli ETag per evitare di recuperare dati invariati, conservare le risposte in cache, ricevere notifiche di modifica grazie ai webhook e rispettare i limiti di frequenza per indirizzo IP e per chiave API.

Un'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-School identifica l'account Omniscol interessato;
  • X-OS-auth contiene 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-Policy indica le quote applicabili, per esempio 60;w=60, 5000;w=86400;
  • RateLimit-Limit indica la quota corrispondente al limite più vicino a essere raggiunto;
  • RateLimit-Remaining indica il numero di richieste ancora disponibili per questa quota;
  • RateLimit-Reset indica 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).

Vedi anche