APIs im Betrieb: Versionierung, Rate Limiting, Paginierung, Fehler

Sobald eine API produktiv genutzt wird, entscheiden ein paar Betriebsthemen darüber, ob Integrationen stabil bleiben. Die folgenden Punkte sind branchenüblich und durch HTTP-Standards (IETF/RFC) sowie MDN abgedeckt.

Versionierung. APIs ändern sich, bestehende Clients sollen aber nicht plötzlich brechen. Üblich ist eine Version im Pfad, etwa /v1/. Neue, nicht abwärtskompatible Änderungen kommen dann in /v2/, während /v1/ für einen Übergangszeitraum weiterläuft. So können Kunden in ihrem eigenen Tempo migrieren.

Rate Limiting. Um Überlast und Missbrauch zu vermeiden, begrenzt der Server, wie viele Anfragen ein Client in einem Zeitfenster stellen darf. Wird das Limit überschritten, antwortet der Server mit dem Statuscode 429 Too Many Requests. Die Antwort sollte erklären, was passiert ist, und kann einen Retry-After-Header enthalten, der angibt, wie lange der Client warten soll, bevor er es erneut versucht. Retry-After akzeptiert entweder eine Sekundenzahl oder ein HTTP-Datum.

Paginierung. Große Listen werden nicht in einer Antwort ausgeliefert, sondern in Seiten aufgeteilt. Gängig sind zwei Ansätze:

• Offset/Limit (z.B. ?limit=50&offset=100): einfach, aber bei sich ändernden Daten anfällig für Verschiebungen.
• Cursor-basiert (z.B. ?limit=50&cursor=...): der Server gibt einen Zeiger auf die nächste Seite zurück, stabil auch bei vielen Einträgen.

Einheitliche Fehlerformate. Fehler sollten maschinenlesbar und über alle Endpunkte hinweg gleich aufgebaut sein, typischerweise als JSON mit Feldern wie Fehlercode, Meldung und ggf. Details. Das passt zur Empfehlung der Standards, dass die Antwort die Ursache erklären soll. Wichtig ist die korrekte Wahl des Statuscodes (z.B. 400 für fehlerhafte Eingaben, 401/403 für Auth, 404 für nicht gefunden, 429 für Rate Limiting, 5xx für Serverfehler).

Idempotenz bei Wiederholungen. Eine Methode ist idempotent, wenn mehrere identische Anfragen denselben Effekt auf den Server haben wie eine einzelne. Laut RFC 9110 sind GET, HEAD, PUT und DELETE idempotent. Das ist entscheidend für sichere Wiederholungen: Wenn die Verbindung abbricht, bevor der Client die Antwort lesen konnte, darf er eine idempotente Anfrage gefahrlos erneut senden. POST ist nicht idempotent; um es trotzdem sicher wiederholbar zu machen, nutzen viele APIs einen Idempotency-Key, sodass der Server doppelte Anfragen erkennt und nicht doppelt ausführt.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 3600

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Zu viele Anfragen. Bitte später erneut versuchen.",
    "retry_after_seconds": 3600
  }
}

Beispiel einer 429-Antwort mit Retry-After-Header und einheitlichem JSON-Fehlerformat

Quellen

• 429 Too Many Requests MDN Web Docs
• Retry-After header MDN Web Docs
• RFC 6585: Additional HTTP Status Codes (Abschnitt 4, 429 Too Many Requests) IETF / RFC Editor
• RFC 9110: HTTP Semantics (9.2.2 Idempotent Methods, 10.2.3 Retry-After) IETF / RFC Editor