API Tasarımı & Yaşam Döngüsü Yönetimi 32 okunma

API Versioning Stratejileri

API'lerin sürümlenmesi için URL path, header ve query parametresi tabanlı stratejiler, .NET'te ASP.NET Core API Versioning kütüphanesi ile uygulama, geriye dönük uyumluluk, kararsız (breaking) değişikliklerin yönetimi ve en iyi pratikler ele alınır.

API Versioning Stratejileri

API'ler zamanla evrilir; yeni özellikler eklenir, mevcut davranışlar değişir veya kullanımdan kaldırılır. Bu değişiklikler, mevcut istemcileri (client) bozmadan yönetilmelidir. API Versioning (Sürümleme), farklı istemcilerin farklı API sürümlerini kullanmasına izin vererek, geriye dönük uyumluluğu (backward compatibility) sağlayan bir tekniktir. Bu yazıda, en yaygın üç sürümleme stratejisini (URL Path, Header, Query Parameter), .NET'te ASP.NET Core API Versioning kütüphanesi ile uygulama yöntemlerini, hangi stratejinin ne zaman kullanılacağını ve en iyi pratikleri ele alacağız.

1. API Sürümleme Neden Gereklidir?

  • Geriye Dönük Uyumluluk (Backward Compatibility): Eski istemciler, yeni sürümden etkilenmeden çalışmaya devam etmelidir.

  • Kademeli Geçiş (Gradual Migration): İstemciler, kendi hızlarında yeni sürüme geçebilir.

  • Hata Düzeltmeleri ve Güvenlik Yamaları: Kritik düzeltmeler, istemci uyumluluğunu bozmadan yayınlanabilir.

  • Deneyler ve A/B Testleri: Yeni özellikler, belirli bir istemci grubuna açılabilir.

2. Üç Temel Sürümleme Stratejisi

Strateji Örnek Avantajlar Dezavantajlar
URL Path /api/v1/users, /api/v2/users En belirgin, cache dostu, kolay anlaşılır. URI'ler değişir, REST prensiplerine aykırı (kaynak kimliği değişir).
Query Parameter /api/users?version=1, /api/users?version=2 Basit, URI sabit kalır. Cache zorluğu (aynı URL farklı yanıt), API anahtarının bir parçası olarak görülmez.
Header Accept: application/vnd.myapi.v1+json, api-version: 1.0 URI temiz kalır, HTTP standartlarına uygun (Content Negotiation). Kullanıcı tarafından görülmez, tarayıcıda test etmesi zor.

3. .NET'te ASP.NET Core API Versioning ile Uygulama

Kurulum:

bash

dotnet add package Microsoft.AspNetCore.Mvc.Versioning

A. URL Path (Varsayılan)

csharp

// Program.cs
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true; // Yanıt başlığına sürüm bilgisini ekler
});

// Controller
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
public class UsersController : ControllerBase
{
    [HttpGet("{id}")]
    [MapToApiVersion("1.0")]
    public IActionResult GetV1(int id) { ... }

    [HttpGet("{id}")]
    [MapToApiVersion("2.0")]
    public IActionResult GetV2(int id) { ... }
}

B. Query Parameter

csharp

builder.Services.AddApiVersioning(options =>
{
    options.ApiVersionReader = new QueryStringApiVersionReader("api-version"); // varsayılan: "api-version"
});

[ApiController]
[Route("api/[controller]")]
public class UsersController : ControllerBase { ... }

C. Header

csharp

builder.Services.AddApiVersioning(options =>
{
    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
});

D. Birden Fazla Okuyucu (Kombinasyon)

csharp

options.ApiVersionReader = ApiVersionReader.Combine(
    new QueryStringApiVersionReader("v"),
    new HeaderApiVersionReader("api-version")
);

4. Sürüm Uyumluluğu ve Breaking Değişiklikler

Sürüm Numarası (Major.Minor):

  • Major: Geriye dönük uyumlu olmayan (breaking) değişiklikler (ör. parametre tipi değişimi, endpoint silinmesi).

  • Minor: Geriye dönük uyumlu (non-breaking) değişiklikler (ör. yeni alan ekleme, opsiyonel parametre).

.NET'te Sürüm Eşleştirme:

csharp

// Varsayılan sürümü 1.0 olarak ayarla
options.DefaultApiVersion = new ApiVersion(1, 0);

// Eğer sürüm belirtilmemişse varsayılanı kullan
options.AssumeDefaultVersionWhenUnspecified = true;

5. API Sürümleme En İyi Pratikler

  1. Sürümü URI'nin Bir Parçası Yapın (URL Path): En yaygın ve açık yaklaşımdır. Geliştiricilerin ve API tüketicilerinin anlaması kolaydır.

  2. Varsayılan Sürüm Belirleyin: İstemci sürüm belirtmezse, en kararlı sürümü (genellikle en eski) döndürün.

  3. Sürümü Yanıt Başlıklarında Bildirin: ReportApiVersions = true ile istemciye hangi sürümün kullanıldığını bildirin.

  4. Deprecated (Eski) Sürümleri İşaretleyin: [ApiVersion("1.0", Deprecated = true)] ile istemcileri uyarın.

  5. Dokümantasyonu Güncel Tutun: Her sürüm için Swagger/OpenAPI dokümantasyonu sağlayın.

  6. Sürümleme Politikası Belirleyin: Ne zaman major, ne zaman minor sürüm yayınlayacağınızı netleştirin (Semantic Versioning).

  7. URL Path Kullanırken Sürümü Route Attribute'unda Belirtin: [Route("api/v{version:apiVersion}/[controller]")]

6. Hangi Strateji Ne Zaman?

Strateji Kullanım Alanı
URL Path Genel amaçlı, dışa açık (public) API'ler, RESTful API'ler. En çok önerilen yöntem.
Header URI temizliği önemliyse, API anahtarının bir parçası olarak, iç mikroservis iletişimi.
Query Parameter Basit prototipler, hızlı testler. Üretimde önerilmez.

Sonuç:

API sürümleme, API'lerin yaşam döngüsü yönetiminin olmazsa olmazıdır. URL Path, anlaşılabilirliği ve cache dostu yapısıyla en yaygın ve önerilen stratejidir. ASP.NET Core API Versioning kütüphanesi, üç stratejiyi de sorunsuz bir şekilde uygulamanıza olanak tanır. Unutmayın, sürümleme sadece bir teknik değil, aynı zamanda istemci iletişimi ve dokümantasyon stratejisidir.

Tüm yazılar