Die API richtig nutzen: Cache, Webhooks und Ratenbegrenzungen
PremiumEine Integration, die Omniscol jede Minute abfragt, um zu prüfen, ob sich Daten geändert haben, erhält meistens dieselbe Antwort wie beim vorherigen Aufruf. Sie verbraucht unnötig ihr Kontingent und belastet den Server, ohne neue Informationen zu erhalten.
Diese Seite stellt die Mechanismen vor, mit denen sich solche überflüssigen Aufrufe vermeiden lassen, sowie die für die API geltenden Ratenbegrenzungen.
Unveränderte Daten nicht erneut abrufen
Die meisten lesenden Antworten der API enthalten einen ETag-Header, der eine
Version der Antwort kennzeichnet. Speichern Sie diese Kennung zusammen mit den
empfangenen Daten und übermitteln Sie sie beim nächsten Aufruf im Header
If-None-Match:
curl -i -G "https://votre-etablissement.omniscol.com/api/schedules/lessons/20261102-20261108" \
-H "Authorization: Bearer $TOKEN" \
-H 'If-None-Match: W/"os1.…"'
Haben sich die Daten nicht geändert, antwortet Omniscol mit 304 Not Modified,
ohne Antwortkörper. Sie können dann die zwischengespeicherten Daten
weiterverwenden. Andernfalls erhalten Sie eine vollständige Antwort 200 OK
mit einem neuen ETag.
Der ETag ist ein undurchsichtiger Wert: Speichern Sie ihn und senden Sie ihn
unverändert zurück, einschließlich der Anführungszeichen und des Präfixes W/,
ohne zu versuchen, ihn zu konstruieren oder zu entschlüsseln. Er gehört zu der
Anfrage, die ihn erzeugt hat, und zu dem verwendeten Zugang: Verwenden Sie ihn
weder für eine andere URL noch mit einem anderen Token.
Der Header Cache-Control: private, no-cache legt fest, dass die Antwort in
einem privaten Cache gespeichert werden darf, vor ihrer Wiederverwendung aber
bei Omniscol revalidiert werden muss. Genau dafür ist If-None-Match da.
Manche Antworten enthalten keinen ETag, insbesondere wenn sie vom aktuellen Datum abhängen und sich ändern können, ohne dass die Daten des Kontos geändert wurden. Diese Antworten müssen bei jedem Aufruf neu abgerufen werden.
Nach der Bereitstellung einer neuen Omniscol-Version werden die ETags
erneuert, auch wenn sich die Daten nicht geändert haben. Der erste Aufruf
erhält dann eine Antwort 200, danach können die folgenden Aufrufe wieder von
den Antworten 304 profitieren.
Das 304 verringert auch den Verarbeitungsaufwand auf der Serverseite. In den
meisten Fällen kann Omniscol, wenn sich seit dem letzten Aufruf keine Daten
des Kontos geändert haben, antworten, ohne die betroffenen Daten überhaupt
erneut zu lesen, und dieses 304 wird dann nicht auf das Kontingent Ihres
API-Schlüssels angerechnet. Ein 304, das nach erneutem Lesen der Daten
erzeugt wird, zählt dagegen wie eine gewöhnliche Antwort.
Die regelmäßige Revalidierung bleibt somit günstig, solange die Daten unverändert sind. Sie unterliegt jedoch weiterhin der allgemeinen Begrenzung pro IP-Adresse.
Antworten zwischenspeichern
Wenn mehrere Benutzer oder mehrere Bildschirme Ihrer Anwendung dieselben Daten abrufen, ist es unnötig, Omniscol für jeden von ihnen abzufragen.
Speichern Sie die Antworten und ihre ETags in einem Anwendungs-Cache unter
Ihrer Kontrolle, zum Beispiel Redis, Memcached oder einer Datenbanktabelle.
Ihre Anwendung kann die Daten dann aus diesem Cache ausliefern, der sie in
regelmäßigen Abständen oder bei einer Änderungsmeldung durch einen Webhook mit
If-None-Match bei Omniscol revalidiert.
Der Cache-Schlüssel muss die vollständige URL, das verwendete
Authentifizierungstoken und, sofern Sie davon Gebrauch machen, den Körper der
GET-Anfrage sowie die Header berücksichtigen, die die Antwort variieren
lassen, etwa Accept-Language. Zwei Token mit unterschiedlichen
Rechten können Zugriff auf unterschiedliche Daten geben: Eine mit dem einen
erhaltene Antwort darf niemals an einen Benutzer ausgeliefert werden, dessen
Rechte den Zugriff darauf nicht erlauben.
Speichern Sie außerdem den Körper jeder Antwort zusammen mit ihrem ETag. Ohne
die zugehörigen Daten lässt sich aus einer Antwort 304 das erwartete
Ergebnis nicht rekonstruieren.
Dieser Anwendungs-Cache ist von einem gemeinsam genutzten HTTP-Cache zu
unterscheiden: Die Direktive Cache-Control: private verbietet diesem, die
Antworten zu speichern.
Benachrichtigungen erhalten, statt regelmäßig abzufragen
Statt regelmäßig zu prüfen, ob sich Daten geändert haben, können Sie Omniscol bitten, Ihre Anwendung zu benachrichtigen, sobald eine Änderung stattfindet.
Dieser Mechanismus beruht auf Webhooks, die im Bildschirm zur Anpassung der API konfiguriert werden (siehe API-Anpassung). Ein Webhook kann einen bestimmten Endpunkt überwachen oder ein Ereignis, das mehrere Änderungen zusammenfasst, etwa die Änderung eines Stundenplans.
Den Cache beim Empfang eines Webhooks invalidieren
Die einfachste Verwendung besteht darin, den Webhook als Invalidierungssignal zu behandeln.
Trifft eine Benachrichtigung ein, markiert Ihre Anwendung die betroffenen Daten als veraltet und revalidiert sie bei Omniscol. Der Inhalt der Änderung muss nicht ausgewertet werden: Der Webhook zeigt lediglich an, dass eine erneute Prüfung nötig ist.
Dieses Vorgehen lässt sich natürlich mit dem zuvor beschriebenen Cache kombinieren.
Unterrichtsstunden per Differenz synchronisieren
Wenn Sie eine synchronisierte Kopie der Unterrichtsstunden pflegen, können Sie mit der Option Mit Daten des Ereignisses zur Stundenplanänderung eine Differenz erhalten, die die hinzugefügten, geänderten und gelöschten Unterrichtsstunden enthält.
Ihre Anwendung kann dann ausschließlich diese Änderungen übernehmen, ohne den gesamten Stundenplan erneut abzurufen.
Den Empfang der Benachrichtigungen sicherstellen
Omniscol unternimmt pro Webhook nur einen einzigen Sendeversuch. Es wartet höchstens vier Sekunden, wiederholt den Versuch bei einem Fehlschlag nicht und hält diesen in seinen Protokollen fest.
Ihr Server muss den Empfang daher schnell bestätigen, mit einer Antwort
200 OK oder 202 Accepted, und die erforderliche Verarbeitung anschließend
asynchron durchführen.
Behalten Sie außerdem eine regelmäßige Revalidierung als Auffangmechanismus
bei. War Ihr Server beim Versand eines Webhooks nicht erreichbar, lassen sich
mit dieser Prüfung die verpassten Änderungen erkennen. Dank der Antworten
304 bleibt sie günstig, wenn die Daten aktuell sind.
Webhooks absichern
Um zu prüfen, dass eine Benachrichtigung tatsächlich von Omniscol stammt, konfigurieren Sie einen benutzerdefinierten HTTP-Header mit einem Geheimnis, das nur Ihre Anwendung und Omniscol kennen. Ihr Server muss Aufrufe ablehnen, die den erwarteten Wert nicht enthalten.
Zwei zusätzliche Header liefern Informationen zum Kontext der Benachrichtigung:
X-Schoolkennzeichnet das betroffene Omniscol-Konto;X-OS-authenthält das Authentifizierungstoken des Benutzers, der die Änderung ausgelöst hat.
Das in X-OS-auth übermittelte Token ist vertraulich. Speichern Sie es nicht
in Ihren Protokollen, geben Sie es nicht an andere Dienste weiter und
beschränken Sie den Zugriff darauf strikt.
Nur die benötigten Daten anfordern
Eine Antwort mit weniger Daten lässt sich in der Regel schneller erzeugen, übertragen und zwischenspeichern.
Begrenzen Sie bei Unterrichtsstunden den angeforderten Zeitraum und filtern Sie die Ergebnisse nach den Entitäten, die Sie interessieren (siehe API der Unterrichtsstunden).
Für Suchen bietet der Endpunkt search/query Filter, die Projektion von
Feldern und die Paginierung (siehe Erweiterte Abfragen).
Um viele gleichartige Elemente (Klassen, Räume, Fächer usw.) zu aktualisieren, bevorzugen Sie Endpunkte, mit denen sich eine vollständige Sammlung in einer einzigen Anfrage übermitteln lässt, sofern sie in der OpenAPI-Dokumentation verfügbar sind, statt zahlreiche Einzelaufrufe auszuführen.
Ratenbegrenzungen einhalten
Für Aufrufe der API gelten zwei Ratenbegrenzungen. Wird eine Begrenzung
erreicht, antwortet Omniscol mit 429 Too Many Requests und einem Header
Retry-After, der die Anzahl der Sekunden angibt, die bis zur Wiederholung
der Anfrage zu warten sind.
Begrenzung pro IP-Adresse
Die allgemeine Begrenzung liegt bei 300 Anfragen innerhalb von 10 Sekunden, über alle Endpunkte der API hinweg, einschließlich MCP und Anzeigetafeln.
Dieser Schwellenwert genügt in der Regel für eine korrekt konzipierte Integration. Er kann jedoch durch Aufrufschleifen ohne Verzögerung oder durch eine übermäßige Zahl paralleler Anfragen erreicht werden.
Begrenzung pro API-Schlüssel
Die Token desselben API-Schlüssels teilen sich zwei Kontingente:
- 60 Anfragen pro Minute;
- 5 000 Anfragen pro Tag.
Die Antworten können die folgenden Header enthalten, mit denen sich der Verbrauch verfolgen lässt:
RateLimit-Policygibt die geltenden Kontingente an, zum Beispiel60;w=60, 5000;w=86400;RateLimit-Limitgibt das Kontingent an, das der Begrenzung entspricht, die am ehesten erreicht wird;RateLimit-Remaininggibt die Anzahl der für dieses Kontingent noch verfügbaren Anfragen an;RateLimit-Resetgibt die Anzahl der Sekunden bis zu seiner Erneuerung an.
Diese Header fehlen insbesondere in Antworten 304, die ohne erneutes Lesen
der Daten erzeugt werden: Ihr Fehlen bedeutet nicht, dass das Kontingent
erschöpft ist.
Ist das Kontingent erschöpft, gibt die Antwort 429 die Wartezeit außerdem in
ihrem Körper an, im Feld retry_after.
Antworten 304, die ohne erneutes Lesen der Daten erzeugt werden, werden nicht
auf diese Kontingente angerechnet, unterliegen aber weiterhin der allgemeinen
Begrenzung pro IP-Adresse.
Wenn diese Begrenzungen eine legitime Nutzung der API behindern, kontaktieren Sie uns, anstatt die Zahl der Schlüssel zu vervielfachen.
Fehler und Wiederholungsversuche behandeln
Nach einer Antwort 429
Halten Sie die in Retry-After angegebene Wartezeit ein, bevor Sie die Anfrage
wiederholen. Sofortiges Wiederholen ist nutzlos und kann die Situation
verlängern, insbesondere wenn mehrere Prozesse Ihrer Anwendung gleichzeitig
neue Versuche unternehmen.
Nach einem Serverfehler oder einer Zeitüberschreitung
Nach einem Fehler 5xx oder einer Überschreitung der Wartezeit kann eine
lesende Anfrage mit zunehmendem Abstand zwischen den Versuchen wiederholt
werden: zum Beispiel eine Sekunde, dann zwei, dann vier, bis zu einer
maximalen Anzahl von Versuchen.
Bei einer schreibenden Anfrage sieht es anders aus: Die Änderung kann gespeichert worden sein, auch wenn die Antwort Sie nie erreicht hat. Prüfen Sie den tatsächlichen Zustand der Daten, bevor Sie den Vorgang wiederholen, um doppelte Änderungen zu vermeiden.
Nach einer Antwort 401
Eine Antwort 401 Unauthorized lässt sich in der Regel nicht durch einen
erneuten Versuch mit demselben Token beheben. Sie kann insbesondere anzeigen,
dass das Token abgelaufen ist, dass sein API-Schlüssel gelöscht wurde oder
abgelaufen ist oder dass der angeforderte Endpunkt nicht zu den von ihm
erlaubten gehört.
Prüfen Sie das Token und die zugehörigen Berechtigungen, bevor Sie den Aufruf wiederholen (siehe Omniscol-API).