APIs entwickeln sich weiter. Neue Funktionen, Korrekturen, veraltete Funktionen. Clients sind jedoch von der aktuellen Schnittstelle abhängig. Die Versionierung ermöglicht eine Weiterentwicklung, ohne bestehende Anwendungen zu zerstören. In diesem Leitfaden werden Strategien und Best Practices vorgestellt.
Warum Version
Kompatibilität
Alte Kunden arbeiten weiter.
Evolution
Verbessern Sie sich, ohne zu blockieren.
Dokumentation
Klarheit darüber, was Sie erwartet.
Übergang
Zeit für die Kundenmigration.
Wann zur Version
Breaking Changes
Änderungen, die Verträge brechen.
Beispiele
- Feld entfernen
- Datentyp ändern
- Bedeutung ändern
- Endpunkt entfernen
Nicht versionieren für
Ergänzungen, die grundsätzlich kompatibel sind.
Versionierungsstrategien
URLPath
/api/v1/users, /api/v2/users.
Abfrageparameter
/api/users?version=1.
Kopfzeile
Accept-Version: v1 oder API-Version: 2.
Inhaltsverhandlung
Accept: application/vnd.myapi.v1+json.
URL-Pfadversionierung
Vorteile
Sichtbar, klar, einfach zu verlegen.
Nachteile
URLs ändern sich je nach Version.
Beispiel
GET /api/v1/products GET /api/v2/products
Häufig
Beliebtester Ansatz.
Header-Versionierung
Vorteile
Saubere, semantisch korrekte URLs.
Nachteile
Weniger sichtbar, schwieriger zu testen.
Beispiel
GET /api/products Header: API-Version: 2
Semantische Versionierung
Format
MAJOR.MINOR.PATCH.
WICHTIG
Bahnbrechende Veränderungen.
GERINGER
Kompatible Ergänzungen.
PATCH
Coole Käfer.
Für APIs
Generell nur MAJOR in der öffentlichen Version.
veraltet
Prozess
Vor dem Entfernen als veraltet markieren.
Kommunikation
Header, Dokumentation, Änderungsprotokoll.
Zeitleiste
Migrationsfrist.
Unterstützung
Wie lange soll die veraltete Version beibehalten werden?
Sunset-Header
HTTPHeader
Sunset: Sat, 01 Jul 2024 00:00:00 GMT.
Deprecation-Header
Zeigt an, dass es veraltet ist.
Kommunikation
Clients können automatisch erkennen.
Migration
Dokumentation
Was hat sich geändert, wie kann man sich anpassen?
Anleitungen
Migration Schritt für Schritt.
Unterstützung
Hilfe beim Übergang.
Zeitleiste
Angemessene Frist.
Abwärtskompatibilität
Ziel
Neue Clients, alte APIs funktionieren.
Zusatzstoff
Hinzufügen, nicht entfernen.
Standardwerte
Neue Felder mit Standardwerten.
###Optional
Neue optionale Parameter.
Vorwärtskompatibilität
Konzept
Alte Kunden mit neuen APIs.
Unbekannt ignorieren
Unbekannte Felder ignorieren.
###Anmutige Erniedrigung
Arbeiten Sie ohne neue Funktionen.
Design für Evolution
Erweiterbarkeit
Denken Sie über zukünftige Veränderungen nach.
Generische Strukturen
Erweiterbare Objekte.
Feature-Flags
Legen Sie keine unvollständigen Funktionen offen.
Verträge
Definieren Sie klar, was Sie versprechen.
Mehrere Versionen
Wartung
Kosten für die Wartung mehrerer.
Grenzen
Wie viele gleichzeitig unterstützt werden sollen.
Politik
Legen Sie klare Regeln fest.
Dokumentation
Nach Version
Versionsspezifische Dokumente.
Änderungsprotokoll
Was sich zwischen den Versionen geändert hat.
Migrationsleitfäden
So aktualisieren Sie.
Hinweise zur veralteten Version
Was dabei herauskommen wird.
Werkzeuge
OpenAPI/Swagger
Versionierte Spezifikation.
Postbote
Sammlungen nach Version.
API-Gateways
Versionsrouting.
Häufige Fehler
Version zu viel
Neue Version für jede Änderung.
Nicht versionieren
Breaking Change ohne neue Version.
Schnell veraltet
Man lässt keine Zeit für die Migration.
Keine Kommunikation
Kunden von Veränderungen überrascht.
SDKs und Clients
Entsprechende Versionen
SDK v1 für API v1.
Wartung
Halten Sie die SDKs auf dem neuesten Stand.
Kommunikation
Benachrichtigen Sie über neue Versionen.
Fazit
API-Versionierung ist eine langfristige Disziplin. Wählen Sie eine klare Strategie, kommunizieren Sie Änderungen und planen Sie Zeit für die Migration ein. Das Ergebnis sind APIs, die sich weiterentwickeln, ohne dass Integrationen unterbrochen werden.
##FAQs
1) Welche Versionierungsstrategie soll verwendet werden? Der URL-Pfad ist am gebräuchlichsten und wird für die meisten empfohlen.
2) Wann sollte die Hauptversion erhöht werden? Für wichtige Änderungen, die nicht abwärtskompatibel sind.
3) Wie lange wird die alte Version unterstützt? Üblich sind 6–12 Monate. Es kommt auf die Kunden an.
4) Kann ich Änderungen ohne Versionierung vornehmen? Ergänzungen grundsätzlich ja. Keine Entfernungen/Änderungen.
5) Wie melde ich eine veraltete Version? Header, Dokumente, E-Mails, Übergangszeitraum.
Lesen Sie auch
- GraphQL für Anwendungen: Implementierungshandbuch
- Backend für Anwendungen: Architektur, Technologien und Best Practices
- Microservices in Anwendungen: Verteilte Architektur für Mobilgeräte
- API für Anwendungen
- API für Anwendungen – Schritt für Schritt im Alltag
- API für Anwendungen – Schritt für Schritt zur Skalierung