REST API Versionierung: Strategien und Best Practices

IRC-Mania Die Seite rund um Sicherheit und Programmierung

Internet, Sicherheit , Internet Relay Chat

Gesponsert

REST API Versionierung sorgt dafür, dass bestehende Clients auch bei Änderungen der API weiterhin stabil funktionieren können.

Kompakte Beschreibung

REST API Versionierung ist die gezielte Steuerung von Änderungen an einer Schnittstelle, damit bestehende Clients nicht durch neue Features oder veränderte Datenformate beeinträchtigt werden. Es gibt verschiedene Strategien, die am häufigsten im Pfad, über Header oder über Content Negotiation umgesetzt werden. Eine gute Versionierungsstrategie definiert klare Regeln für inkompatible und kompatible Änderungen, kommuniziert Deprecations früh und ermöglicht einen geordneten Übergang von einer Version zur nächsten. Versionierung ist kein technisches Detail, sondern ein wesentlicher Bestandteil des API-Lifecycle-Managements und der langfristigen Beziehung zu den Nutzern der Schnittstelle.

Wichtige REST API Komponenten

Inkompatible und kompatible Änderungen unterscheiden

Nicht jede Änderung an einer API erfordert eine neue Version. Das Hinzufügen optionaler Felder, neuer Endpunkte oder zusätzlicher Filter ist kompatibel und kann ohne neue Version eingeführt werden. Inkompatible Änderungen wie das Entfernen von Feldern, das Ändern von Datentypen oder das Verschieben von Endpunkten erfordern eine neue Version, damit bestehende Clients nicht brechen.

URI Versioning

Beim URI Versioning wird die Version direkt in die URL eingebettet, beispielsweise /v1/customers oder /api/v2/orders. Das ist die einfachste und verbreitetste Variante, weil die Version auf einen Blick sichtbar ist und problemlos in Links, Logs und Caching verwendet werden kann.

Header Versioning

Beim Header Versioning wird die Version über einen eigenen Header wie api-version: 1 oder Accept-Version: v2 übermittelt. Die URL bleibt sauber, aber die Version ist für Betrachter der URL nicht direkt ersichtlich. Diese Variante ist gut geeignet, wenn die API-Oberfläche unabhängig von der URL bleiben soll.

Content Negotiation

Bei der Content Negotiation teilt der Client über den Accept Header mit, welche Version er erwartet, beispielsweise Accept: application/vnd.shop.v1+json. Das ist sehr flexibel, aber auch komplexer in der Implementierung und für weniger erfahrene Nutzer schwerer zu verstehen.

Semantische Versionierung

Semantische Versionierung, bekannt aus der Softwareentwicklung, kann auch für APIs genutzt werden. Major Versionen signalisieren inkompatible Änderungen, Minor Versionen neue kompatible Features und Patch Versionen kleine Korrekturen. Für APIs wird oft nur die Major Version in der URL sichtbar gemacht.

Deprecation und Sunset

Wenn eine API Version abgelöst werden soll, kennzeichnest Du sie als deprecated. Informiere Nutzer frühzeitig über das End-of-Life, dokumentiere die Migration und gib genügend Zeit für den Umstieg. Header wie Sunset oder Deprecation helfen, das Ende einer Version maschinenlesbar anzuzeigen.

Versionierung in der Dokumentation

Jede Version sollte klar dokumentiert sein, inklusive Änderungsprotokoll, Migrationsanleitung und unterstützter Zeitrahmen. Nutzer müssen schnell erkennen, welche Version sie verwenden und welche Änderungen eine neue Version mit sich bringt.

Caching und Versionierung

Caching muss bei Versionierung beachtet werden. URLs mit Version im Pfad sind besonders cachefreundlich, weil unterschiedliche Versionen unterschiedliche URLs haben. Bei Header Versioning ist Vorsicht geboten, weil Caches oft nur die URL als Schlüssel verwenden und Header ignorieren.

Backward Compatibility

Backward Compatibility bedeutet, dass neue Versionen nicht die alte Version beeinträchtigen. Alte Versionen bleiben für die angekündigte Unterstützungszeit erreichbar. Vermeide es, alte Versionen vorzeitig abzuschalten, ohne Nutzer ausreichend informiert zu haben.

API Versionierung als Prozess

Versionierung funktioniert nur, wenn sie im Team als Prozess verankert ist. Klare Regeln für Releases, Reviews, Kommunikation und Monitoring sind notwendig. Jede Version sollte eine definierte Besitzerrolle und einen klaren Lebenszyklus haben.

Praxisbeispiel REST API Versionierung

Ein Software-as-a-Service Anbieter betreibt eine Kunden-API. Nach zwei Jahren sollen die Adressdaten strukturiert werden, was eine inkompatible Änderung darstellt.

Alte Version v1:

GET /v1/customers/42
{
  "id": 42,
  "name": "Musterfirma GmbH",
  "address": "Musterstraße 12, 10115 Berlin"
}

Neue Version v2:

GET /v2/customers/42
{
  "id": 42,
  "name": "Musterfirma GmbH",
  "address": {
    "street": "Musterstraße 12",
    "zip": "10115",
    "city": "Berlin",
    "country": "DE"
  }
}

Kommunikation an die Nutzer:

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Link: </v2/customers/42>; rel="successor-version"

So können bestehende Clients die v1 weiterhin nutzen, während sie rechtzeitig auf v2 migrieren. Die neue Version ist klar erreichbar, die alte Version wird planvoll abgelöst.

IRC-Security.de

Cybersecurity Artikel und Tutorials

FAQ: REST API Versionierung

Weiter im API Lernpfad

Der nächste Artikel im API Lernpfad behandelt REST API Fehlerbehandlung: Statuscodes und Error Objects — wie Du Fehler in APIs strukturiert, standardkonform und client-freundlich behandelst.

Quellen

1. https://www.rfc-editor.org/rfc/rfc9110
2. https://opensource.zalando.com/restful-api-guidelines/index.html
3. https://developer.mozilla.org/docs/Web/HTTP/Headers/Accept

Buchempfehlungen zur API-Entwicklung

Wenn Du Dich weiter mit API Versionierung, API Design und Softwarearchitektur beschäftigen möchtest, empfehlen wir Dir die folgenden Bücher:

API-Entwicklung

Bücher über API-Design, REST, GraphQL, OpenAPI und API-Architektur

REST und HTTP: Entwicklung und Integration nach REST-Prinzipien von Stefan Tilkov

Bei Amazon ansehen

Affiliate-Link: Bei einem Kauf erhalten wir möglicherweise eine Provision.

API-Design: Praxishandbuch für Java- und Webservice-Entwickler

Bei Amazon ansehen

Affiliate-Link: Bei einem Kauf erhalten wir möglicherweise eine Provision.

Microservices: Grundlagen flexibler Softwarearchitekturen von Eberhard Wolff

Bei Amazon ansehen

Affiliate-Link: Bei einem Kauf erhalten wir möglicherweise eine Provision.

Premium VPS Hosting

Schnelle und sichere VPS Server

Gesponsert