Versiyonlama stratejileri

API'ler zamanla evrilir: yeni alanlar eklenir, eski alanlar deprecated olur, davranis degisir. Versiyonlama stratejisi, bu evrimi kontrollu yönetmek ve mevcut istemcileri kirici degisikliklerden korumak icin tasarlanir. Doğru strateji URI path, HTTP header, query parametresi veya medya tipi uzerinden secilebilir. Her yaklasimin operasyonel, cache ve istemci deneyimi acisindan trade-off'lari vardir. Versiyonlama sadece teknik bir URL meselesi degil; ürün, destek ve dokumantasyon sureclerini de kapsayan organizasyonel bir taahhuttur.

Breaking ve non-breaking değişiklikler

Breaking change ornekleri: alan silme, alan tipi değiştirme, zorunlu alan ekleme, varsayilan davranis degisikligi, hata kodu anlam degisikligi. Non-breaking change: opsiyonel alan ekleme, yeni endpoint, yeni enum degeri (dikkatli; bilinmeyen enum istemcileri kirabilir), genisletilmis filtre parametresi. Versiyonlama breaking change'leri major surumde toplar; istemciler bilincli geçiş yapar. Minor surumler geriye uyumlu kalmalidir.

URI path versiyonlama

En görünür yöntem: /api/v1/products, /api/v2/products. Avantajlar: açık, cache ve routing kolay, dokumantasyon net, gateway kurallari basit. Dezavantajlar: URI kalabaligi, HATEOAS link guncellemesi, çoklu kod yolu bakimi.

GET /api/v1/orders/{id}   // v1: flat shipping address
GET /api/v2/orders/{id}   // v2: nested address + lineItems expand

Gateway ve reverse proxy path bazli yonlendirme yapabilir. Eski versiyon ayri deployment veya ayni kodda adapter ile calisabilir. CDN cache path versiyonuna gore ayrilir; karistirma riski düşüktür.

Header ve medya tipi versiyonlama

Accept: application/vnd.company.v2+json veya özel header Api-Version: 2. URI temiz kalir; ayni URL farklı sözleşme dondurur. Dezavantaj: cache zorlasir, Vary: Accept veya Vary: Api-Version gerekir. Test ve dokumantasyon daha az görünür; istemci header'i bilincli gondermelidir.

GET /api/orders/42
Accept: application/vnd.myapi.orders.v2+json
Api-Version: 2.0

Medya tipi versiyonlama REST purist yaklasimidir; öğrenme egrisi yüksektir ancak kaynak URI'si evrimden bagimsiz kalir.

Query string versiyonlama

GET /api/products?api-version=2 basit prototipler ve geçici geçiş icin kullanılır. Cache key karmasiklasir; log analizi zorlasir. Genelde kalıcı strateji olarak onerilmez ancak legacy istemcileri hızlı tasimak icin geçici çözüm olabilir. Query versiyonu belirsiz isteklerde varsayilan surume dusmelidir.

Yöntem karsilastirmasi

• URI path: En yaygın, en açık, cache dostu, gateway routing kolay.
• Header: Temiz URL, Vary gerekir, SDK header yönetimi sart.
• Query: Basit ama cache ve güvenlik loglari zayif.
• Medya tipi: REST uyumlu, vendor media type kaydi gerekir.

Semantic versioning ve API

API semver: MAJOR breaking, MINOR additive, PATCH bug fix. Sürüm numarasi versiyonlama stratejisiyle eslestirilir. v1 icinde MINOR değişiklikler backward compatible olmalidir. MAJOR yeni path veya header gerektirir. Sürüm numarasi ile deployment surumu karistirilmamali; API v2 ayri servis olabilir veya monolith icinde adapter olabilir.

Deprecation ve Sunset header'lari

Deprecation: true
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: <https://docs.example.com/migration/v2>; rel="deprecation"

Minimum destek suresi (örneğin 12 ay) dokumante edilir. Metriklerle eski versiyon kullanımı izlenir; sifira yakinlayinca kapatma planlanir. Kapatmadan once istemcilere e-posta, changelog ve SDK uyarı mesajlari gonderilir. Zorunlu versiyon gecisi icin iletişim plani onceden hazirlanir.

ASP.NET Core ApiVersioning

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader = ApiVersionReader.Combine(
        new UrlSegmentApiVersionReader(),
        new HeaderApiVersionReader("Api-Version"));
})
.AddMvc()
.AddApiExplorer(options => options.GroupNameFormat = "'v'VVV");

Controller'da [ApiVersion("1.0")] ve [ApiVersion("2.0")] ile çoklu implementasyon sunulur. Minimal API'de MapGroup("/api/v{version:apiVersion}") kullanılır. Swagger her versiyon icin ayri doküman üretir.

Gateway routing ve çoklu backend

API gateway path veya header'a gore backend servis versiyonuna yonlendirir. Örnek: /v1/* legacy monolith'e, /v2/* yeni microservice'e. Canary release: v2 trafik yuzdesi kademeli artirilir; hata orani esik asarsa rollback hızlı yapilir. Gateway'de versiyon bazli rate limit ve auth policy uygulanabilir.

Veri adapter ve DTO katmanı

Ayni veritabanindan v1 ve v2 farklı DTO doner. Adapter katmanı domain entity'den her versiyon icin map yapar. v1'de deprecated alan hala doldurulur; v2'de kaldirilir veya yeniden yapilandirilir. Okuma agir sistemlerde read model versiyonlanabilir. Yazma path'inde v1 istemcisi gonderdigi eski şema ile calismaya devam eder.

OpenAPI ve istemci SDK

Her major versiyon ayri OpenAPI dosyasi: openapi-v1.yaml, openapi-v2.yaml. Swagger UI versiyon secici sunar. Client SDK her major icin ayri NuGet/npm paketi uretilebilir: MyApi.Client.V1, MyApi.Client.V2. CI pipeline her versiyon icin contract test calistirir.

Breaking change yönetim süreci

1. Değişiklik RFC veya ADR ile onerilir.
2. Breaking mi additive mi siniflandirilir.
3. Migration rehberi ve kod ornekleri yazilir.
4. Deprecation header ve dokumantasyon güncellenir.
5. Metrik esik asildiginda eski versiyon kapatilir.

GraphQL ve REST versiyonlama farki

GraphQL genelde versiyonsuz evrim tercih eder: deprecated field directive, yeni field ekleme. REST'teki major versiyon GraphQL'de schema evolution ile karsilanir. Karma mimaride tutarlılık zor; ekip politikasi net olmalidir. Federation ortaminda subgraph versiyonlari ayri yönetilir.

Test, anti-kaliplar ve özet

Contract test her desteklenen versiyon icin çalışır. Regression suite v1 istemci simulasyonu yapar. Anti-kaliplar: versiyonsuz breaking change; sonsuz v1 destegi; belirsiz deprecation tarihi; dokumantasyonsuz v2. API versiyonlama kontrollu evrim sağlar; URI path çoğu ekip icin en pratik secimdir.

Surumler arasi veri migrasyonu

v1'den v2'ye geciste istemci veri donusumunu ustlenebilir veya sunucu geçiş katmanı saglayabilir. Dual-write donemi: hem eski hem yeni şema yazilir; okuma tek kaynaktan yapilir. Bu dönem kisa tutulmali ve otomasyon ile izlenmelidir. Veritabanı şema degisikligi API versiyonundan bagimsiz yönetilir; expand-contract pattern uygulanir: once yeni kolon ekle, sonra istemcileri taşı, sonra eski kolonu kaldir.

Organizasyonel sahiplik

Her major versiyon icin sahip ekip ve kapatma tarihi product roadmap'e islenir. Destek ekibi hangi versiyonlarin aktif oldugunu tek sayfadan gorebilmelidir. Istemci kullanım metrikleri (header veya path'ten) otomatik toplanir; manuel anket yerine gerçek trafik verisi karar verdirir.

Blue-green ve parallel run

Major versiyon gecislerinde blue-green deployment iki API surumunu ayni anda calistirir. Trafik DNS veya gateway ile kademeli kaydirilir. Parallel run doneminde v1 ve v2 ayni veritabanına yaziyorsa schema uyumlulugu genisletilmis tutulmalidir. Read path'lerde v2 yeni alanlari doldururken v1 eski alanlari okumaya devam eder. Cutover gecesi rollback plani ve iletişim listesi hazir olmalidir.

Contract-first versiyon planlama

OpenAPI diff araclari breaking degisiklikleri otomatik isaretler. CI pipeline'da PR acildiginda v1 ile v2 şema karsilastirmasi çalışır. Silinen alan, tip degisikligi veya zorunlu alan ekleme build'i kirar. Ekipler versiyon gecisini kod review'dan once şema review ile baslatir. Spectral ve openapi-diff bu surecte yaygın araclardir.

Istemci upgrade dalgasi yönetimi

Mobil uygulamalar zorunlu güncelleme mekanizmasi ile eski API surumlerini kullanmayi birakabilir. Web istemcileri genelde ayni gun deploy edilir. B2B entegrasyonlarinda 6-12 ay migration penceresi sağlanır. Her istemci grubu icin hedef kapatma tarihi ve iletişim sorumlusu atanir. Kullanım metrikleri haftalik raporlanir.

Feature flag ile davranis versiyonlama

Bazi değişiklikler URI versiyonu gerektirmeden feature flag ile acilir. Flag tenant veya istemci bazinda acilip kapanabilir. Flag kalıcı davranis degisikligine donusurse major versiyon planlanir. Flag ile versiyonlama karistirildiginda dokumantasyon ve test matrisi hizla karmasiklasir; sınır cizilmelidir.