Die API richtig nutzen: Cache, Webhooks und Ratenbegrenzungen

Premium

Aufrufe der Omniscol-API optimieren: ETags nutzen, um unveränderte Daten nicht erneut abzurufen, Antworten zwischenspeichern, Änderungsbenachrichtigungen über Webhooks erhalten und die Ratenbegrenzungen pro IP-Adresse und pro API-Schlüssel einhalten.

Eine 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-School kennzeichnet das betroffene Omniscol-Konto;
  • X-OS-auth enthä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-Policy gibt die geltenden Kontingente an, zum Beispiel 60;w=60, 5000;w=86400;
  • RateLimit-Limit gibt das Kontingent an, das der Begrenzung entspricht, die am ehesten erreicht wird;
  • RateLimit-Remaining gibt die Anzahl der für dieses Kontingent noch verfügbaren Anfragen an;
  • RateLimit-Reset gibt 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).

Siehe auch