Was sind die wichtigsten API-Versioning-Strategien und wie deprecatest du eine Version?

Question

IT Interview Practice · Accepted Answer

Versioning erlaubt dir, eine API mit **Breaking Changes** weiterzuentwickeln, ohne bestehende Clients zu brechen. Es gibt drei Mainstream-Strategien plus einen Deprecation-Prozess.

## Die drei Strategien

**1. URI-Versioning** — die Version steht im Pfad.
```http
GET /v1/users/42 HTTP/1.1
GET /v2/users/42 HTTP/1.1
```
Am einfachsten und sichtbarsten; leicht zu routen, zu cachen und im Browser zu testen. Nachteil: es verletzt technisch "der URI identifiziert eine Ressource" (derselbe User hat jetzt zwei URLs). Das ist mit Abstand die häufigste Wahl (GitHub, Stripe historisch).

**2. Custom-Header-Versioning** — die Version reist in einem Header.
```http
GET /users/42 HTTP/1.1
X-API-Version: 2
```
Hält URLs sauber, ist aber im Browser unsichtbar und schwerer zu cachen.

**3. Media-Type- (Content-Negotiation-)Versioning** — Version im `Accept`.
```http
GET /users/42 HTTP/1.1
Accept: application/vnd.example.v2+json
```
Am "RESTful-sten" (die Ressourcen-URL ist stabil; nur ihre Repräsentation wird versioniert), aber für Konsumenten am wenigsten zugänglich.

## Was als Breaking zählt

```text
BREAKING      → remove/rename a field, change a type, change auth, tighten validation
NON-BREAKING  → add a new optional field, add a new endpoint, add an enum value*
```
Nur Breaking Changes brauchen eine neue Version; füge Non-Breaking-Änderungen der aktuellen hinzu.

## Deprecation-Prozess

1. **Ankündigen** mit Daten in Docs und Changelog.
2. **Zur Laufzeit signalisieren** mit Headern, damit Clients es programmatisch bemerken:
```http
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Jan 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users/42>; rel="successor-version"
```
3. **Überwachen**, wie stark die alte Version genutzt wird, und verbleibende Aufrufer kontaktieren.
4. **Sunset** erst, wenn die Nutzung nahe null fällt.

## Warum es wichtig ist

Interviewer fragen das, um zu sehen, ob du eine API in Produktion wachsen lassen kannst, ohne die davon abhängigen Clients zu brechen — ein echtes operatives Anliegen, kein theoretisches. Die stärksten Antworten treffen zwei Unterscheidungen: erstens, dass **die meisten Änderungen non-breaking sind** und überhaupt keinen Versionssprung auslösen sollten (additive Änderungen gehen in die aktuelle Version), und Versioning für wirklich brechende Änderungen reserviert bleibt; und zweitens, dass die *Strategie* weniger zählt als der *Prozess* — eine klare Deprecation-Timeline mit `Deprecation`/`Sunset`-Headern und Nutzungsüberwachung ist das, was Konsumenten tatsächlich schützt. URI-Versioning gewinnt in der Praxis wegen seiner Sichtbarkeit und Tooling-Unterstützung, aber die Trade-offs zu kennen (Header und Media-Type halten URLs stabil und sind RESTful-er, auf Kosten der Auffindbarkeit) zeigt, dass du den Design-Raum verstehst, statt nur `/v1/` nachzuahmen.

Die drei Strategien

Was als Breaking zählt

Deprecation-Prozess

Warum es wichtig ist

Ähnliche Fragen