API Versioning
API-Versionierung
API-Versionierung ist ein Plan zum Benennen, Ändern, Unterstützen und Zurückziehen von API-Verträgen, ohne Clients zu unterbrechen. Es gibt keine einzige URL oder Header-Stil, den jede API verwenden muss.
Ein weiteres Beispiel
Eine Gehaltsabrechnungs-API veröffentlicht den OpenAPI-Vertrag `2026-07` und hält die `/v1`-Clients funktionsfähig. Hinzufügen eines optionalen Feldes bricht sie nicht. Die Änderung von `netPay` von Ganzzahlcent auf Dezimalwerte erfordert einen neuen Hauptvertrag. Es werden auch Umzugsanleitungen, Deprecation-Header, Nutzungsdaten und ein Rückzugsdatum benötigt.
Hauptteile
- 01Vertragskennzeichen
- 02Kompatibilitätsregeln
- 03Veralterung und Migration
Verwenden Sie es, wenn
Lege zuerst Kompatibilitätsregeln, Änderungsarten, die Entdeckungsmethode, den Unterstützungszeitraum und die Veralterungsrichtlinie fest. Wähle dann einen Pfad, Medientyp oder Header-Stil.
Nutze es nicht, wenn
Erstellen Sie nicht für jede Veröffentlichung eine neue API-Version. Versprechen Sie nicht ewig Unterstützung ohne Nutzungsdaten und eine Möglichkeit, alte Versionen außer Dienst zu stellen.
In Code verwendeter Name
explicit compatibility policy + versioned OpenAPI document + deprecation and sunset lifecycle Vor dem Ausliefern
Check contracts and invariants, authorization, and input limits. Test retries, one-time effects, timeouts, and partial failures. Verify data integrity, compatibility, monitoring, recovery, and rollback.
Outcome: Complete the task with API-Versionierung (API Versioning). User context: Eine Gehaltsabrechnungs-API veröffentlicht den OpenAPI-Vertrag `2026-07` und hält die `/v1`-Clients funktionsfähig. Hinzufügen eines optionalen Feldes bricht sie nicht. Die Änderung von `netPay` von Ganzzahlcent auf Dezimalwerte erfordert einen neuen Hauptvertrag. Es werden auch Umzugsanleitungen, Deprecation-Header, Nutzungsdaten und ein Rückzugsdatum benötigt. Technical concept or control: API-Versionierung (API Versioning). Why it fits: Lege zuerst Kompatibilitätsregeln, Änderungsarten, die Entdeckungsmethode, den Unterstützungszeitraum und die Veralterungsrichtlinie fest. Wähle dann einen Pfad, Medientyp oder Header-Stil. Do not use it when: Erstellen Sie nicht für jede Veröffentlichung eine neue API-Version. Versprechen Sie nicht ewig Unterstützung ohne Nutzungsdaten und eine Möglichkeit, alte Versionen außer Dienst zu stellen. Engineering requirements: Define inputs, outputs, contracts, and rules that must always hold. Set authorization and input checks. Define failures, timeouts, retries, one-time effects, data moves, and compatibility limits. Operations: Add useful signals and logs that hide sensitive data. Set capacity limits and write an operator guide. Test recovery and rollback. Acceptance criteria: Contract and failure-path tests pass. Data and authorization rules still hold during retries and partial failures. Check performance limits, monitoring, recovery, and rollback. Evidence and limits (evidence boundary): Kein einziger offizieller Standard kontrolliert den gesamten Begriff. Seine Bedeutung kann sich zwischen Teams, Plattformen oder Frameworks ändern. Unknowns to confirm: Where the code runs, data stores, traffic shape, consistency needs, and the security boundary. Also confirm the compatibility period, service goals, and rollback limits.
Diese Anfrage prüfen
Review how API-Versionierung (API Versioning) is used now. Definition: API-Versionierung ist ein Plan zum Benennen, Ändern, Unterstützen und Zurückziehen von API-Verträgen, ohne Clients zu unterbrechen. Es gibt keine einzige URL oder Header-Stil, den jede API verwenden muss. Release checks: Check contracts and invariants, authorization, and input limits. Test retries, one-time effects, timeouts, and partial failures. Verify data integrity, compatibility, monitoring, recovery, and rollback. Before changing code, list the evidence, gaps, severity, and the smallest safe fix.