Verbrauchsgrenzen für PHP-APIs schützen die Verfügbarkeit und die Kosten des Dienstes. Eine schlecht entworfene Richtlinie kann jedoch legitime Integrationen unterbrechen. Eine Zahl für Anfragen pro Minute festzulegen, reicht nicht aus: Entscheidend ist, wer die API nutzt, welchen Vorgang diese Person oder Anwendung ausführt, welche Ressource gefährdet ist und wie sich der reale Datenverkehr verhält.
Ein wirksames Design kombiniert Grenzen, die zum Nutzungsmuster passen, konsistente Zähler über mehrere Instanzen hinweg und Antworten, mit denen sich API-Nutzer erholen können. Außerdem muss die Wirkung der Regeln beobachtet werden, bevor sie verschärft werden – insbesondere dann, wenn mehrere Clients dieselben Zugangsdaten verwenden oder auf gemeinsame Ressourcen angewiesen sind.
Anfragerate, Kontingent und Parallelität unterscheiden
Diese Kontrollen schützen vor unterschiedlichen Problemen und sind nicht austauschbar:
- Anfragerate: Begrenzt, wie viele Anfragen innerhalb eines kurzen Zeitraums angenommen werden. So lassen sich Lastspitzen oder anhaltender Datenverkehr eindämmen, der die Anwendung überlastet.
- Kumuliertes Kontingent: Begrenzt den Gesamtverbrauch über einen längeren Zeitraum, zum Beispiel eine bestimmte Anzahl von Vorgängen pro Tag oder Abrechnungszeitraum. Damit lässt sich die vertraglich vereinbarte Nutzung oder die kumulierte Ausführung kostspieliger Aufgaben steuern.
- Parallelität: Begrenzt, wie viele Vorgänge gleichzeitig ausgeführt werden. Das ist sinnvoll, wenn einzelne Vorgänge über längere Zeit Worker, Verbindungen oder andere Ressourcen belegen können.
Ein Client kann die Anfragerate einhalten und trotzdem viele lang laufende Vorgänge gleichzeitig ansammeln. Ebenso kann er nur wenige Anfragen stellen, die aber ein kostspieliges Tageskontingent aufbrauchen. Lege die Kontrolle anhand des Risikos fest, das du verringern möchtest. Wenn mehrere Kontrollen erforderlich sind, definiere, wie sie zusammenwirken und welche zuerst greift.
Festlegen, welche Identität und Ressource begrenzt wird
Der Schlüssel für die Begrenzung sollte eine Verbrauchseinheit abbilden, die betrieblich sinnvoll ist. Je nach Produkt kann es sich um Zugangsdaten, einen Benutzer, eine Organisation, eine Clientanwendung, eine Route oder eine Kombination daraus handeln. Eine Begrenzung allein anhand der IP-Adresse kann gemeinsam genutzte Netzwerke benachteiligen und authentifizierte Nutzer nur unzureichend unterscheiden. Eine IP-Adresse kann als ergänzendes Signal für anonymen Datenverkehr oder Sicherheitskontrollen dienen.
Bei authentifizierten Clients empfiehlt es sich, die Richtlinie an eine stabile Identität zu knüpfen und Organisationen voneinander zu isolieren. Werden Zugangsdaten von mehreren Systemen gemeinsam verwendet, lässt sich möglicherweise nicht erkennen, welches System eine Lastspitze verursacht. Verwende nach Möglichkeit getrennte Zugangsdaten oder ergänze weitere Dimensionen, anhand derer sich der Verbrauch zuordnen lässt. Nimm unveränderte Geheimnisse weder in Zählerschlüssel noch in Protokolle auf.
Nicht alle Routen verursachen dieselben Kosten. Eine einfache Abfrage und ein umfangreicher Export sollten nicht zwangsläufig dasselbe Kontingent verbrauchen. Für kostspielige Vorgänge kannst du unterschiedliche Gewichtungen oder Richtlinien festlegen, sofern die Kriterien für die API-Nutzer verständlich und konsistent sind. Berücksichtige auch die Grenzen des Dienstes: Eine API kann nur wenige Anfragen erhalten und trotzdem eine gemeinsam genutzte Abhängigkeit wie eine Datenbank oder einen externen Anbieter überlasten.
Zeitfenster passend zum Nutzungsmuster wählen
Ein festes Zeitfenster lässt sich einfach erklären, kann aber am Ende eines Intervalls eine Lastspitze und gleich zu Beginn des nächsten eine weitere zulassen. Ein gleitendes Zeitfenster verringert diesen Effekt, erfordert dafür jedoch mehr Speicher- und Rechenaufwand. Ein Token-System erlaubt begrenzte Lastspitzen bei kontrollierter Durchschnittsrate und eignet sich, wenn legitimer Datenverkehr schubweise eintrifft. Welche Variante passt, hängt vom Verbrauchsmuster und von der erforderlichen Genauigkeit ab.
Verwechsle eine legitime Aktivitätsspitze nicht mit Missbrauch. Geplante Aufgaben, Synchronisierungen zu Beginn des Arbeitstags oder Wiederholungsversuche nach einer Unterbrechung können Anfragen bündeln. Wenn das Produkt Lastspitzen zulässt, lege deren Umfang und die Zeit bis zur Wiederherstellung des Kontingents ausdrücklich fest. Begrenze bei lang laufenden Vorgängen zusätzlich die Parallelität oder setze eine Zulassungssteuerung ein, bevor knappe Ressourcen belegt werden.
Auch Wiederholungsversuche auf Client-Seite sind relevant. Wenn eine temporäre Antwort sofortige Wiederholungsversuche auslöst, kann die Begrenzung die Lastspitze noch verschärfen. Empfiehl eine schrittweise Verzögerung, idealerweise mit zufälliger Streuung, und lege fest, ob wiederholte Vorgänge mit demselben Idempotenzschlüssel als neue Anfragen oder als sichere Wiederholung zählen.
Zähler koordinieren, wenn PHP auf mehreren Instanzen läuft
Ein Zähler, der nur im Prozessspeicher abgelegt wird, kann auf einer einzelnen Instanz funktionieren, bleibt bei der Verteilung des Datenverkehrs auf mehrere Instanzen aber nicht konsistent. Jeder Server könnte einen Teil des Grenzwerts akzeptieren, sodass er insgesamt überschritten wird. Bei Deployments mit mehreren Instanzen muss der Zustand über einen gemeinsam genutzten Speicher oder einen gleichwertigen Mechanismus mit geeigneten atomaren Operationen koordiniert werden.
Lege auch fest, wie sich das System verhält, wenn der Zählerspeicher ausfällt. Ist er nicht verfügbar, kann die Ablehnung sämtlicher Anfragen legitime Clients unterbrechen; alle Anfragen anzunehmen kann dagegen eine kritische Abhängigkeit gefährden. Die Entscheidung hängt vom Risiko der Route ab: Bei einer Abfrage mit geringen Auswirkungen kann ein anderes Fehlerverhalten angemessen sein als bei einem Vorgang, der hohe Kosten verursacht. Dokumentiere die Entscheidung und richte Warnmeldungen für Beeinträchtigungen ein.
Vermeide zu allgemein gehaltene Zählerschlüssel, durch die Organisationen oder Routen vermischt werden, ebenso wie eine zu starke Aufteilung, die die Kontrolle des Gesamtverbrauchs erschwert. Lege eine Ablaufzeit und eine Bereinigung des Zustands fest, damit temporäre Schlüssel nicht unbegrenzt anwachsen. Prüfe, dass Konfigurationsänderungen Zähler nicht unerwartet zurücksetzen oder duplizieren.
Ablehnungen als Teil des API-Vertrags kommunizieren
Wenn ein Grenzwert erreicht ist, gib einen HTTP-Status zurück, der mit dem API-Vertrag übereinstimmt – bei einer Ratenbegrenzung üblicherweise 429 Too Many Requests – sowie einen strukturierten Antwortkörper, der die Art der Begrenzung nennt, ohne interne Informationen offenzulegen. Wird der Vorgang aus einem anderen Grund abgelehnt, verwende diesen Status nicht irreführend.
Gib hilfreiche Hinweise zur Wiederherstellung, zum Beispiel den voraussichtlichen Zeitpunkt für einen erneuten Versuch oder die im Vertrag definierten Angaben zu Grenzwert und Verbrauch. Wenn du Retry-After sendest, stelle sicher, dass der Wert eine gültige Wartezeit angibt. Sorge für konsistente Antworten über alle Routen hinweg und vermeide es, Zähler anderer Clients offenzulegen. API-Nutzer müssen eine vorübergehende Ablehnung von Authentifizierungs-, Validierungs- oder Verfügbarkeitsfehlern unterscheiden können.
Auswirkungen beobachten und anhand von Belegen anpassen
Protokolliere angenommene und abgelehnte Anfragen, Identität oder Kundensegment auf sichere Weise, Route, angewandte Richtlinie und Ablehnungsgrund. Miss außerdem Latenz, Parallelität und die Auslastung relevanter Abhängigkeiten. Speichere weder Zugangsdaten noch unnötige personenbezogene Daten; wenn geschützte oder aggregierte Kennungen für die Analyse ausreichen, verwende diese.
Ein Anstieg der Ablehnungen beweist für sich genommen nicht, dass der Grenzwert zu streng ist. Suche nach Mustern: betroffene Clients, Uhrzeiten, Routen, Dauer der Vorgänge und anschließende Wiederholungsversuche. Prüfe Hinweise auf falsch positive Ablehnungen, etwa eine Häufung bei Organisationen mit gemeinsam genutzten Zugangsdaten oder bei geplanten Aufgaben. Ändere jeweils nur eine Variable und halte eine Möglichkeit bereit, die Änderung zurückzunehmen.
Die Richtlinie schrittweise einführen
Bevor du einen Grenzwert durchsetzt, bewerte die Richtlinie anhand von Nutzungsdaten und teste repräsentative Szenarien. Wenn es die Architektur erlaubt, protokolliere, welche Anfragen abgelehnt worden wären, ohne sie tatsächlich zu blockieren. Diese Beobachtung ersetzt weder Lasttests noch garantiert sie, dass historische Daten alle Lastspitzen vorhersagen.
- Lege fest, welches Risiko du kontrollieren möchtest und ob dafür eine Anfragerate, ein Kontingent, eine Begrenzung der Parallelität oder eine Kombination erforderlich ist.
- Weise Grenzen nach Identität und Ressource zu und prüfe die Isolation zwischen Benutzern und Organisationen.
- Teste Lastspitzen, langsame Vorgänge, Wiederholungsversuche, gemeinsam genutzte Zugangsdaten und Ausfälle des Zählerspeichers.
- Prüfe, ob mehrere Instanzen den Grenzwert koordiniert durchsetzen und der temporäre Zustand bereinigt wird.
- Validiere die Ablehnungsantwort, die Hinweise für Wiederholungsversuche und die Kompatibilität mit den bestehenden API-Nutzern.
- Überwache Ablehnungen, Latenz und Abhängigkeiten. Informiere über Änderungen, die sich auf Integrationen auswirken können.
Verbrauchsgrenzen für PHP-APIs müssen sowohl die Plattform als auch die Kontinuität für Clients schützen. Die beste Richtlinie ist nicht die strengste, sondern jene, die Risiken mit eindeutig zuordenbaren Regeln, vorhersehbaren Antworten und ausreichender Datengrundlage kontrolliert, um unerwünschte Auswirkungen zu korrigieren.
