C# Academy · Lektion

Strategien für API-Versionierung

Versionieren Sie über URL, Header und Query-String.

Strategien für API-Versionierung ist eine kostenlose C# Academy-Lektion auf CoddyKit. Dies ist Lektion 1 von 4. Du kannst die komplette Lektion unten kostenlos lesen – dann übst du sie direkt im Browser mit einem integrierten Code-Editor und einem KI-Tutor rund um die Uhr. Sie ist Teil des C# Academy-Lernpfads, und dein Fortschritt wird über Web und CoddyKit-App synchronisiert. Der C# Academy-Kurs umfasst insgesamt 4 Lektionen.

Warum eine API versionieren?

Sobald Clients von Ihrer API abhängen, dürfen Sie ihren Vertrag nicht mehr brechen. Versionierung ermöglicht es Ihnen, inkompatible Änderungen in einer neuen Version bereitzustellen, während alte Clients weiterhin mit der alten Version funktionieren.

// v1 returns { name }
// v2 returns { firstName, lastName }  (breaking)

Versionierung im URL-Pfad

Bei der sichtbarsten Strategie steht die Version im Pfad. Das ist eindeutig und erleichtert Routing, Navigation und Caching.

GET /api/v1/products
GET /api/v2/products

Versionierung über den Query-String

Die Version wird als Query-Parameter übertragen. URLs bleiben stabil, und ein fehlender Parameter kann standardmäßig auf die neueste oder eine festgelegte Version verweisen.

GET /api/products?api-version=1.0
GET /api/products?api-version=2.0

Versionierung über Header

Ein benutzerdefinierter Request-Header enthält die Version, sodass die URL übersichtlich bleibt. Der Nachteil: Im Adressfeld des Browsers ist die Version nicht sichtbar und manuelle Tests sind schwieriger.

GET /api/products
X-Api-Version: 2.0

Versionierung über den Medientyp

Diese Strategie wird auch Inhaltsaushandlung genannt. Die Version ist im Medientyp des Accept-Headers eingebettet. Sie ist die REST-konformste, aber am schwersten auffindbare Option.

GET /api/products
Accept: application/json;v=2.0

Die Strategien vergleichen

Jede Strategie stellt die Auffindbarkeit der Übersichtlichkeit von URLs gegenüber:

URL-Pfad: am leichtesten auffindbar, macht URLs unübersichtlicher.
Query-String: stabile URLs, einfache Standardwerte.
Header: übersichtliche URLs, in Browsern verborgen.
Medientyp: am stärksten an REST orientiert, am schwierigsten zu verwenden.

// Many teams pick URL path for public APIs

Semantische Versionierung von APIs

API-Versionen werden normalerweise nur als Major-Version angegeben (v1, v2). Reservieren Sie Minor-Versionen für zusätzliche, rückwärtskompatible Änderungen, die alte Clients ignorieren können.

// v1.0 -> v1.1 : additive (safe)
// v1   -> v2   : breaking (new version)

Veraltete Versionen

Entfernen Sie eine alte Version niemals abrupt. Kennzeichnen Sie sie als deprecated, kündigen Sie ein Abschaltdatum an und signalisieren Sie dies den Clients über Header.

// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: true

Standardversion

Legen Sie fest, was geschieht, wenn ein Client keine Version sendet. Häufige Optionen sind: die neueste Version annehmen, v1 annehmen oder die Anfrage ablehnen. Eindeutige Regeln vermeiden Überraschungen.

// Strategy: unversioned request -> treat as v1.0

Die richtigen Dinge versionieren

Versionieren Sie den Vertrag (Routen sowie Anfrage- und Antwortstrukturen) und nicht interne Implementierungsdetails. Ein v2-Endpunkt kann den Großteil der Geschäftslogik mit v1 gemeinsam nutzen.

// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2Controller

Strategien kombinieren

Die Versionierungsbibliothek von ASP.NET Core kann die Version gleichzeitig aus mehreren Quellen lesen. Dadurch können Clients die jeweils bequemste Variante wählen. Dies konfigurieren Sie im nächsten Schritt.

// Accept version from URL OR header OR query

Kurze Überprüfung

Testen Sie Ihr Verständnis der Versionierungsstrategien.

Zusammenfassung

Sie haben verschiedene Strategien zur API-Versionierung kennengelernt:

URL-Pfad, Query-String, Header und Medientyp.
Jede Strategie stellt die Auffindbarkeit der Übersichtlichkeit von URLs gegenüber.
Versionieren Sie den Vertrag, kündigen Sie veraltete Versionen geordnet ab und definieren Sie eine Standardversion.

Als Nächstes: Asp.Versioning in ASP.NET Core konfigurieren.

Häufig gestellte Fragen

Ist die Lektion „Strategien für API-Versionierung“ kostenlos?

Ja — der vollständige Text von „Strategien für API-Versionierung“ ist hier im Web kostenlos zu lesen. Um sie interaktiv zu üben (integrierter Code-Editor und 24/7 KI-Tutor) und den Rest des C# Academy-Kurses freizuschalten, upgrade auf CoddyKit PRO. Der C# Academy-Kurs umfasst insgesamt 4 Lektionen.

Was lerne ich in „Strategien für API-Versionierung“?

Versionieren Sie über URL, Header und Query-String. Du übst C# Academy mit praktischem Code, den du direkt im Browser ausführst, und ein 24/7 KI-Tutor beantwortet deine Fragen während du die Lektion bearbeitest.

Brauche ich Erfahrung, um C# Academy zu starten?

Keine Vorkenntnisse erforderlich. C# Academy auf CoddyKit ist für Anfänger bis fortgeschrittene Lernende strukturiert, sodass du hier starten oder von Anfang an beginnen und in deinem eigenen Tempo voranschreiten kannst. Dies ist Lektion 1 von 4.

Wie lange dauert die Lektion „Strategien für API-Versionierung“?

Die meisten CoddyKit-Lektionen dauern etwa 5–10 Minuten. Jede ist kompakt und interaktiv, sodass du stetig Fortschritte machst und genau dort weitermachst, wo du aufgehört hast – im Web und in der App.

Kann ich in dieser C# Academy-Lektion Code schreiben und ausführen?

Ja. Jede C# Academy-Lektion enthält einen integrierten Code-Editor, sodass du echten Code direkt in deinem Browser schreibst und ausführst und sofort KI-Feedback erhältst — ohne lokale Einrichtung erforderlich.

Alle Lektionen in diesem Kurs

← Zurück zu C# Academy