.NET API: Versionierung und Best Practices

API-Versionierung ist ein entscheidender Aspekt der Enterprise-Anwendungsentwicklung. Sie ermöglicht die Einführung von Änderungen, ohne bestehende Clients zu beeinträchtigen. Dieser Artikel präsentiert einen umfassenden Leitfaden zur API-Versionierung in .NET mit ASP.NET Core.

Warum ist API-Versionierung wichtig?

Wenn sich Anwendungen weiterentwickeln, ändern sich APIs:

• Neue Funktionen - Hinzufügen neuer Endpunkte
• Breaking Changes - Änderung von Verträgen
• Optimierung - Verbesserung der Leistung
• Deprecation - Auslaufen alter Funktionen
• Rückwärtskompatibilität - Unterstützung älterer Clients

API-Versionierungsstrategien

1. URL Path Versioning

Beliebteste Methode - Version im URL-Pfad:

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    public ActionResult<IEnumerable<ProductV1>> GetV1()
    {
        return Ok(new[] { new ProductV1 { Id = 1, Name = "Product" } });
    }
    
    [HttpGet]
    [MapToApiVersion("2.0")]
    public ActionResult<IEnumerable<ProductV2>> GetV2()
    {
        return Ok(new[] { 
            new ProductV2 { 
                Id = 1, 
                Name = "Product",
                Description = "Neues Feld in v2"
            } 
        });
    }
}

Vorteile:

• Einfach zu verwenden und zu verstehen
• Sichtbar in der URL
• Gut für Dokumentation
• Cache-freundlich

Nachteile:

• URL kann lang werden
• Code muss für jede Version dupliziert werden

2. Header Versioning

Version im HTTP-Header:

[ApiController]
[Route("api/products")]
[ApiVersion("1.0")]
[ApiVersion("2.0")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    public ActionResult<IEnumerable<ProductV1>> GetV1() { }
    
    [HttpGet]
    [MapToApiVersion("2.0")]
    public ActionResult<IEnumerable<ProductV2>> GetV2() { }
}

Client sendet: api-version: 2.0 Header

3. Query String Versioning

Version als Query-Parameter:

[ApiController]
[Route("api/products")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    public ActionResult<IEnumerable<ProductV1>> GetV1() { }
}

Aufruf: GET /api/products?api-version=2.0

Konfiguration in ASP.NET Core

Paketinstallation

dotnet add package Asp.Versioning.Mvc
dotnet add package Asp.Versioning.Mvc.ApiExplorer

Grundkonfiguration

// Program.cs
var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
}).AddApiExplorer(options =>
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

var app = builder.Build();
app.MapControllers();
app.Run();

Best Practices

1. Semantische Versionierung

Verwenden Sie semantische Versionierung (MAJOR.MINOR.PATCH):

[ApiVersion("1.0")]  // Erste Veröffentlichung
[ApiVersion("1.1")]  // Neue Funktionen, rückwärtskompatibel
[ApiVersion("2.0")]  // Breaking Changes

2. API-Version-Deprecation

Markieren Sie veraltete Versionen:

[ApiVersion("1.0", Deprecated = true)]
[ApiVersion("2.0")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    [Obsolete("Verwenden Sie v2.0")]
    public ActionResult<ProductV1> GetV1()
    {
        Response.Headers.Add("X-API-Warn", 
            "Diese Version ist veraltet. Verwenden Sie v2.0");
        return Ok(/* ... */);
    }
}

3. Dokumentation mit Swagger

Swagger-Integration für jede Version:

builder.Services.AddSwaggerGen(options =>
{
    var provider = builder.Services.BuildServiceProvider()
        .GetRequiredService<IApiVersionDescriptionProvider>();
    
    foreach (var description in provider.ApiVersionDescriptions)
    {
        options.SwaggerDoc(
            description.GroupName,
            new OpenApiInfo
            {
                Title = $"Meine API {description.ApiVersion}",
                Version = description.ApiVersion.ToString(),
                Description = description.IsDeprecated 
                    ? "Diese API-Version ist veraltet" 
                    : ""
            });
    }
});

Testen verschiedener Versionen

public class ProductsControllerTests
{
    [Fact]
    public async Task GetV1_ReturnsProductsWithoutDescription()
    {
        var client = _factory.CreateClient();
        var response = await client.GetAsync("/api/v1/products");
        
        response.EnsureSuccessStatusCode();
        var products = await response.Content
            .ReadFromJsonAsync<List<ProductV1>>();
        Assert.NotNull(products);
    }
    
    [Fact]
    public async Task GetV2_ReturnsProductsWithDescription()
    {
        var client = _factory.CreateClient();
        var response = await client.GetAsync("/api/v2/products");
        
        response.EnsureSuccessStatusCode();
        var products = await response.Content
            .ReadFromJsonAsync<List<ProductV2>>();
        Assert.All(products, p => Assert.NotNull(p.Description));
    }
}

API-Versionierungs-Checkliste

Vor der Bereitstellung der Versionierung sicherstellen:

• [ ] Versionierungsstrategie ausgewählt (URL/Header/Query)
• [ ] Semantische Versionierung angewendet
• [ ] Standardversion konfiguriert
• [ ] Veraltete Versionen markiert
• [ ] Swagger-Dokumentation für jede Version
• [ ] Tests für alle Versionen
• [ ] Breaking Changes dokumentiert
• [ ] Migrationsleitfaden erstellt
• [ ] Versionsspezifisches Monitoring aktiviert
• [ ] Sunset-Policy definiert
• [ ] Client-Bibliotheken aktualisiert
• [ ] Client-Kommunikation über Änderungen

Versionsmigration

Sunset-Header

Informieren Sie Clients über den Ruhestand der Version:

[ApiVersion("1.0", Deprecated = true)]
public class ProductsController : ControllerBase
{
    [HttpGet]
    [MapToApiVersion("1.0")]
    public ActionResult<ProductV1> GetV1()
    {
        Response.Headers.Add("Sunset", 
            "Sat, 31 Dec 2024 23:59:59 GMT");
        Response.Headers.Add("Link", 
            "</api/v2/products>; rel=\"successor-version\"");
        return Ok(/* ... */);
    }
}

Zusammenfassung

Gute API-Versionierung in .NET erfordert:

• Klare Strategie - Methode wählen und dabei bleiben
• Dokumentation - Swagger für jede Version
• Tests - Coverage für alle Versionen
• Kommunikation - Clients über Änderungen informieren
• Schrittweise Auslaufphase - Zeit für Migration geben

Richtige Versionierung ermöglicht API-Evolution ohne bestehende Integrationen zu beeinträchtigen.

Benötigen Sie Hilfe mit APIs?

Bei MDS Software Solutions Group bieten wir:

• API-Architekturdesign
• Versionierungsimplementierung
• Audit bestehender APIs
• Migration zu neuen Versionen
• 24/7 technischen Support

Kontaktieren Sie uns, um Ihr Projekt zu besprechen!