ASP.NET API Versioning ile Sürüm Yönetimi

ASP.NET API Versioning Nedir?

ASP.NET API Versioning, API'lerinizin farklı sürümlerini aynı anda yönetebilmenize olanak sağlayan güçlü bir süreçtir. Yazılım mimarisinde sürümleme; API'yi kullanan uygulamaların geriye dönük uyumluluğunu koruyarak, yeni özellikler eklemenize ve hata düzeltmeleri yapmanıza olanak tanır. ASP.NET API Versioning, hem büyük projelerde hem de büyümekte olan uygulamalarda sürdürülebilirlik ve esneklik açısından kritik öneme sahiptir.

Neden API Sürümleme Yapılır?

API'lerde değişiklik yapmak kaçınılmazdır. Özellikle sürekli güncellenen ve büyüyen projelerde, kullanıcıların eski sürümleri bozulmadan yeni özellikler alması önemlidir. Sürümleme sayesinde API'nizin birden fazla versiyonu bir arada çalışabilir ve eski istemciler güvenle hizmet almaya devam eder. Ayrıca, yazılım ekibi kod tabanında daha esnek çalışabilir ve değişikliklerin yayılmasını kontrollü gerçekleştirebilir.

ASP.NET API Versioning Nasıl Kurulur?

ASP.NET Core projelerinde Microsoft.AspNetCore.Mvc.Versioning NuGet paketiyle kolayca kurulabilir. Kurulum sonrasında, controller veya action başına sürüm atayarak farklı sürümlerin yönetimini sağlayabilirsiniz. Aşağıda temel bir kurulum örneği görebilirsiniz:

// NuGet'te şu komut ile yükleme yapılır:
// dotnet add package Microsoft.AspNetCore.Mvc.Versioning

// Program.cs veya Startup.cs içinde:
services.AddApiVersioning(options => {
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});

API Sürümleri Nasıl Tanımlanır?

Sürümler controller seviyesinde attribute olarak tanımlanabilir. Örneğin iki farklı versiyona sahip bir controller aşağıdaki gibi yazılır:

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class ProductsController : ControllerBase
{
    [HttpGet]
    public IActionResult GetV1() => Ok("V1 Ürün Listesi");
}

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("2.0")]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult GetV2() => Ok("V2 Ürün Listesi");
}

Sürüm Bilgisi Nasıl Gönderilir?

API istemcileri, sürüm bilgisini genellikle URL üzerinde, istek başlıklarında (header) ya da sorgu parametresiyle gönderebilir. En yaygın yöntemlerden biri URL tabanlıdır:

GET /api/v1/Products
GET /api/v2/Products

Sonuç

ASP.NET API Versioning, uzun vadede API'nizin yönetilebilir, esnek ve sürdürülebilir kalmasını sağlar. Gerekli olduğunda API'de yenilikler yaparken mevcut kullanıcıların süreklilik beklentisini karşılamak için sürümleme büyük kolaylık sunar. ASP.NET API Versioning ile sürüm yönetimi, modern web servisleri geliştirmek isteyen herkes için vazgeçilmez bir yapı taşını temsil eder.