API Deprecation: Definition, Best Practices, Beispiele

Was ist API Deprecation?

API Deprecation ist der formale Prozess, einen API-Endpoint, eine Version, einen Parameter oder ein Response-Feld auszulaufen. Das deprecated Thing funktioniert während einer Sunset-Period weiter, aber Consumer werden gewarnt zu migrieren. Eventuell wird das deprecated Piece entfernt (genannt "Sunset"), und Clients, die es noch aufrufen, brechen.

Deprecation ist der Vertrag zwischen API-Provider und Consumern: "Wir ändern das. Hier ist die Timeline. Hier ist die Alternative."

Deprecation-Lifecycle

HTTP-Standards für Deprecation

HTTP/1.1 200 OK
Deprecation: Sat, 1 Jun 2026 00:00:00 GMT
Sunset: Sat, 1 Dec 2026 00:00:00 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

Was deprecated wird

• Ganze API-Versionen
• Spezifische Endpoints
• Request-Parameter
• Response-Fields
• Authentication-Methoden
• Webhook-Event-Types
• SDK-Methods

Deprecation Best Practices

• Früh ankündigen. 6+ Monate.
• Migration-Path dokumentieren.
• Sunset/Deprecation-Headers nutzen.
• Bekannte Consumer emailen.
• Usage tracken.
• Transition-Period mit beiden APIs laufen.
• Versioning-Strategie.
• Changelog dokumentieren.
• Brownouts vor Sunset.

Häufige Deprecation-Fallstricke

• Silent Breakage.
• Kein Migration-Path dokumentiert.
• Sunset-Window zu kurz.
• Field entfernen das noch genutzt wird.
• SDKs vergessen.
• Kein Replacement.
• Communication nur via Blog.

Beispiel: GitHub-API-Deprecation

GitHub kündigt Breaking-Changes ~12 Monate im Voraus an, markiert sie in REST + GraphQL, emailt aktive OAuth-App-Maintainer.

Beispiel: Stripe-API-Versioning

Stripe pinnt jeden API-Key auf ein spezifisches Versions-Datum. Neue Versionen sind Opt-in; alte Versionen werden essentially forever supported.

FAQ: API Deprecation

Wie lang sollte ein Sunset-Window sein?

6+ Monate für kleine Changes; 12+ Monate für große Version-Cuts.

Sollte ich meine API versionieren?

Ja für jede API mit externen Consumern.

Unterschied zwischen Deprecation und Sunset?

Deprecation: angekündigt. Sunset: tatsächlich entfernt.

Wie weiß ich, wer meine deprecated API aufruft?

Per-Endpoint-Usage mit Consumer-ID loggen.

HTTP-Status-Code für Sunset-Endpoints?

410 Gone.

Sollte ich deprecaten oder nur new Fields adden?

Additive Changes sind non-breaking. Deprecate wenn entfernend OR Semantik ändernd.

Was wenn Customers nicht migrieren?

Brownouts vor finalem Sunset.

API-Version-Coexistence mit LoadFocus testen

Während Deprecation-Windows läuft LoadFocus JMeter- und k6-Scripts gegen alte und neue API-Versionen, um Behavior-Consistency zu verifizieren. Registrieren bei loadfocus.com/signup.