Idempotente und versionierte REST-APIs entwerfen

Sie deployen ein neues Feature, und plötzlich erhält Ihre API doppelte POST-Requests von Clients, die nach einem Timeout erneut versuchen. Ihre Datenbank enthält nun zwei identische Bestellungen. Oder Sie rollen eine Breaking Change aus, und Mobile-Apps stürzen ab, weil sie das alte Antwortformat erwartet haben. Das sind zwei der häufigsten und schmerzhaftesten Probleme im API-Design: nicht-idempotente Operationen und Breaking Changes. Dieser Leitfaden zeigt Ihnen, wie Sie beide mit praktischen Mustern für Idempotenz und Versionierung in REST-APIs lösen.

Warum Idempotenz in REST-APIs wichtig ist

Idempotenz bedeutet, dass das mehrfache Ausführen derselben Anfrage denselben Effekt hat wie eine einmalige Ausführung. HTTP-Methoden haben definierte Idempotenz-Semantiken: GET, HEAD, PUT, DELETE und OPTIONS sind idempotent, während POST und PATCH es nicht sind. In der Praxis müssen reale APIs jedoch oft POST für Operationen wie das Erstellen von Ressourcen oder die Verarbeitung von Zahlungen akzeptieren. Netzwerkfehler, Client-Timeouts und Retry-Logik können Duplikate verursachen. Ohne Idempotenz riskieren Sie Doppelbelastungen, doppelte Datensätze oder inkonsistenten Zustand.

Techniken für idempotente REST-APIs

1. Idempotency Keys für POST-Requests verwenden

Der gängigste Ansatz besteht darin, Clients einen eindeutigen Schlüssel (z. B. eine UUID) in einem Idempotency-Key-Header senden zu lassen. Der Server speichert den Schlüssel und das Ergebnis der Operation. Wird derselbe Schlüssel erneut empfangen, gibt der Server das gespeicherte Ergebnis zurück, anstatt die Operation erneut auszuführen.

POST /payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "amount": 1000,
  "currency": "USD"
}

Implementierungsschritte:

1. Der Client generiert für jede logische Operation einen eindeutigen Schlüssel (UUID v4).
2. Der Server prüft, ob der Schlüssel in einem persistenten Speicher (z. B. Redis oder Datenbank) existiert.
3. Falls nicht, wird die Anfrage verarbeitet und der Schlüssel mit Antwortstatus und -body gespeichert.
4. Falls ja, wird die gespeicherte Antwort zurückgegeben, ohne erneut zu verarbeiten.

Legen Sie eine angemessene Ablaufzeit fest (z. B. 24 Stunden), um unbegrenztes Speicherwachstum zu vermeiden.

2. Conditional Requests nutzen

Verwenden Sie für Updates die Header ETag und If-Match, um verlorene Updates zu verhindern. Der Server gibt ein ETag zurück, das den aktuellen Zustand repräsentiert. Der Client sendet es mit If-Match zurück; hat sich die Ressource geändert, gibt der Server 412 Precondition Failed zurück. Dadurch werden PUT-Requests sicher gegen Race Conditions.

PUT /articles/123
If-Match: "abc123"
Content-Type: application/json

{"title": "Updated title"}

3. PUT für natürliche Idempotenz entwerfen

Bevorzugen Sie PUT gegenüber POST, wenn der Client die Ressourcen-URL bestimmen kann. Beispielsweise ist PUT /users/{userId} natürlich idempotent, da wiederholte Aufrufe dieselbe Ressource überschreiben. Verwenden Sie POST nur, wenn der Server die ID zuweist.

4. Duplikaterkennung mit Unique Constraints handhaben

Kombinieren Sie Idempotency Keys mit Datenbank-Unique-Constraints auf Business-Keys (z. B. Bestellnummer). Wenn ein Duplikat durchrutscht, lehnt die Datenbank es ab, und Sie können einen 409 Conflict mit einer klaren Meldung zurückgeben.

Versionierungsstrategien für REST-APIs

APIs entwickeln sich weiter. Neue Felder, geändertes Verhalten oder entfernte Endpunkte können bestehende Clients brechen. Versionierung ermöglicht es Ihnen, Änderungen einzuführen, ohne sie zu stören. Es gibt mehrere gängige Strategien:

Für die meisten Teams ist URI-Path-Versionierung die pragmatischste Wahl. Sie ist sichtbar, einfach zu dokumentieren und funktioniert gut mit API-Gateways und CDNs.

Wie Sie versionieren, ohne Clients zu brechen

1. Beginnen Sie von Anfang an mit v1 im Pfad. Versionierung später hinzuzufügen ist schwieriger.
2. Nur additive Änderungen innerhalb einer Version: neue optionale Felder, neue Endpunkte. Entfernen oder benennen Sie niemals Felder um.
3. Deprecation mit Anstand: kündigen Sie das End-of-Life an, stellen Sie Migrationsleitfäden bereit und überwachen Sie die Nutzung alter Versionen.
4. Sunset-Header verwenden: Sunset: Sat, 31 Dec 2025 23:59:59 GMT, um Clients zu informieren.
5. Halten Sie höchstens zwei aktive Versionen, um den Wartungsaufwand zu begrenzen.

Alles zusammenführen: Ein praktisches Beispiel

Betrachten Sie eine Payment-API. Sie möchten eine Zahlung idempotent erstellen und den Endpunkt versionieren.

POST /v1/payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "amount": 1000,
  "currency": "USD"
}

Server-Logik:

• Prüfen, ob Idempotency-Key in Redis existiert.
• Falls ja, die gecachte Antwort (Status + Body) zurückgeben.
• Falls nein, Zahlung verarbeiten, Schlüssel mit Antwort speichern, 201 Created zurückgeben.

Verwenden Sie für Updates PUT mit ETag:

PUT /v1/payments/123
If-Match: "xyz789"
Content-Type: application/json

{"amount": 1500}

Wenn das ETag nicht übereinstimmt, geben Sie 412 zurück. Dies verhindert das Überschreiben gleichzeitiger Änderungen.

Häufige Fallstricke und wie Sie sie vermeiden

• Idempotency Keys für immer speichern: Legen Sie eine TTL fest (z. B. 24h), um Speicherbloat zu vermeiden.
• Race Conditions ignorieren: Verwenden Sie atomare Operationen (z. B. Redis SETNX), um Schlüssel zu prüfen und zu setzen.
• Zu spät versionieren: Fügen Sie /v1 von Anfang an hinzu.
• Breaking Changes in Minor-Versionen: Behandeln Sie jede Änderung, die die Antwortstruktur verändert, als Major.
• Idempotenz nicht dokumentieren: Geben Sie klar an, welche Endpunkte Idempotency-Key unterstützen.

FAQ

Was ist eine idempotente REST-API?

Eine idempotente REST-API stellt sicher, dass die mehrfache Ausführung derselben Anfrage dasselbe Ergebnis liefert wie eine einmalige Ausführung. Dies ist entscheidend, um Retries sicher zu handhaben, insbesondere bei nicht-idempotenten Methoden wie POST.

Welche HTTP-Methoden sind idempotent?

GET, HEAD, PUT, DELETE, OPTIONS und TRACE sind idempotent. POST und PATCH sind standardmäßig nicht idempotent, aber Sie können sie mit Techniken wie Idempotency Keys idempotent machen.

Was ist die beste Methode zur Versionierung einer REST-API?

URI-Path-Versionierung (z. B. /v1/users) ist der gängigste und praktischste Ansatz. Sie ist explizit, einfach zu routen und funktioniert gut mit Caching und API-Gateways. Andere Optionen sind Query-Parameter, Custom Header und Media Types, aber sie haben Kompromisse.

Bereit, die JSON-Antworten Ihrer API zu testen? Verwenden Sie unseren JSON Formatter, um Payloads schnell zu validieren und hübsch zu formatieren.