API Versioning Nedir, Nasıl Yapılır?

API versioning, modern yazılım mimarilerinde sistemlerin kararlılığını kaybetmeden ve mevcut entegrasyonları bozmadan evrilmesini sağlayan stratejik bir mühendislik sürecidir. Yazılım ekosisteminde istemciler ile sunucular arasındaki veri akışını yöneten API'ler, iş gereksinimlerine ve teknolojik gelişmelere bağlı olarak zamanla yeni işlevler kazanır. Ancak bu güncellenme sürecinde geriye dönük uyumluluğun (backward compatibility) korunması kritik bir gereksinimdir. Bu teknik rehberde, API sürüm yönetimi süreçlerinin mimari altyapısını, farklı sürümleme yaklaşımlarını, endüstri standartlarını ve kurumsal sistemlerde uygulanması gereken modern metodolojileri teknik karar vericiler ve yazılım mimarları için detaylıca inceliyoruz.

API Versioning (Sürüm Yönetimi) Nedir?

Uygulama Programlama Arayüzü (API) sürüm yönetimi, bir API'nin birden fazla sürümünü aynı anda çalıştırarak istemcilerin kendi sistemlerini kesintiye uğratmadan güncellemeleri entegre etmesine olanak tanıyan bir yazılım mühendisliği disiplinidir. Bir API, en yalın tanımıyla sağlayıcı (provider) ile tüketici (consumer/client) arasında yapılmış yazılı olmayan bir sözleşmedir (SLA - Service Level Agreement). Bu sözleşme; gönderilecek veri formatını, kabul edilecek parametreleri, kimlik doğrulama yöntemlerini ve geri dönülecek HTTP durum kodları ile veri şemalarını (payload schema) kesin kurallarla tanımlar.

Yazılım geliştirme yaşam döngüsünde (SDLC) iş ihtiyaçları geliştikçe, veritabanı şemaları değiştikçe veya yeni güvenlik standartları geldikçe bu sözleşmenin güncellenmesi gerekir. Eğer yapılan değişiklikler sözleşmenin temel yapısını bozuyorsa, bu duruma "kırıcı değişiklik" (breaking change) denir. Sürüm yönetimi, bu kırıcı değişikliklerin eski istemcileri devre dışı bırakmasını engellemek amacıyla devreye girer. API sağlayıcısı, eski istemciler için mevcut sözleşmeyi korurken (örneğin v1 sürümü), yeni özellikleri ve yapısal değişiklikleri içeren yeni bir sözleşmeyi (örneğin v2 sürümü) paralel olarak yayına alır.

Kurumsal sistemlerde sürüm yönetimi sadece teknik bir zorunluluk değil, aynı zamanda müşteri memnuniyetini ve operasyonel sürekliliği doğrudan etkileyen ticari bir stratejidir. Stripe, Salesforce veya Twilio gibi küresel ölçekteki API sağlayıcıları, on yılı aşkın süredir eski sürümlerini aktif ve geriye dönük uyumlu tutarak entegratörlerin güvenini kazanmaktadır. Mikroservis mimarilerinin yaygınlaşmasıyla birlikte, servislerin birbirleriyle olan bağımlılıklarını yönetmek de sürüm yönetiminin kapsamına dahil olmuştur. Bağımsız olarak konuşlandırılan (deploy edilen) mikroservislerin, birbirlerinin çalışma süreçlerini kesintiye uğratmaması için API sınırlarının katı bir şekilde sürüm kontrolüne tabi tutulması gerekir.

Neden API Sürüm Yönetimine İhtiyaç Duyulur? (Riskler ve Kırıcı Değişiklikler)

Yazılım projelerinde kontrolsüz API güncellemeleri, doğrudan finansal kayıplara ve marka prestijinin zedelenmesine yol açar. Bir e-ticaret platformunun ödeme geçidi API'sinde yapılan küçük bir alan değişikliği, entegre durumdaki binlerce üye iş yerinin ödeme alamamasına neden olabilir. Bu tür senaryoların önüne geçmek için geriye dönük uyumluluk standartlarının ve kırıcı değişikliklerin sınırlarının çok iyi çizilmesi gerekir.

Geriye Dönük Uyumluluğun (Backward Compatibility) Önemi

Geriye dönük uyumluluk, bir API'nin yeni bir sürümü yayına alındığında, eski sürümü kullanan istemcilerin hiçbir kod değişikliği yapmadan çalışmaya devam edebilmesidir. Mobil uygulamalar bu durumun en somut örneğidir. App Store veya Google Play Store üzerinden yayınlanan bir mobil uygulamanın tüm kullanıcılar tarafından aynı anda güncellenmesi imkansızdır. Kullanıcıların önemli bir kısmı uygulamanın eski sürümlerini kullanmaya devam eder. Eğer backend servislerinde geriye dönük uyumluluk korunmazsa, eski mobil uygulama sürümleri çökecek veya işlevsiz hale gelecektir. Benzer şekilde, IoT (Nesnelerin İnterneti) cihazları gibi gömülü sistemlerde donanım güncellemeleri çok daha yavaş ve zahmetlidir; bu cihazların bağlandığı API'lerin uzun yıllar boyunca geriye dönük uyumlu kalması kritik bir gereksinimdir.

Hangi Durumlar "Kırıcı Değişiklik" (Breaking Change) Kabul Edilir?

Bir değişikliğin "kırıcı" olup olmadığını belirlemek, sürüm stratejisinin temelini oluşturur. Aşağıdaki durumlar doğrudan kırıcı değişiklik sınıfına girer ve kesinlikle yeni bir API sürümü gerektirir:

• Veri Alanlarının Silinmesi veya Yeniden Adlandırılması: Yanıttaki (response payload) veya istekteki (request payload) mevcut bir alanın kaldırılması ya da isminin değiştirilmesi (örneğin, userId alanının user_id yapılması).

• Veri Tiplerinin Değiştirilmesi: Bir alanın veri tipinin değiştirilmesi (örneğin, daha önce tam sayı - integer kabul edilen bir alanın metin - string formatına dönüştürülmesi).

• Zorunlu Yeni Parametrelerin Eklenmesi: İstek gövdesine (body) veya başlığına (header) daha önce olmayan ve gönderilmesi zorunlu (required) hale getirilen yeni bir parametrenin eklenmesi.

• Validasyon Kurallarının Sıkılaştırılması: Mevcut bir alanın kabul ettiği karakter sınırının düşürülmesi, regex kontrolünün daraltılması veya isteğe bağlı (optional) bir alanın zorunlu hale getirilmesi.

• HTTP Durum Kodlarının Değiştirilmesi: Başarılı bir işlem sonrası dönen 200 kodunun 201 olarak değiştirilmesi veya hata durumunda dönen 400 yerine 422 dönülmesi (istemciler hata kodlarına göre spesifik akışlar yönetiyor olabilir).

• Semantik Değişiklikler: Bir API endpoint'inin davranışının kökten değişmesi (örneğin, /cancel-order endpoint'inin siparişi iptal etmek yerine siparişi iade sürecine sokması).

Versiyonlama Gerektirmeyen Güvenli Değişiklikler

Her değişiklik yeni bir ana sürüm (major version) çıkarılmasını gerektirmez. Aşağıdaki güncellemeler geriye dönük uyumlu kabul edilir ve mevcut sürüm üzerinde güvenle uygulanabilir:

• Yeni Endpoint Eklenmesi: Mevcut akışları etkilemeyen tamamen bağımsız yeni bir kaynağın (resource) veya endpoint'in sisteme dahil edilmesi.

• İsteğe Bağlı (Optional) Parametre Eklenmesi: İstek gövdesine veya sorgu parametrelerine, gönderilmesi zorunlu olmayan yeni alanların eklenmesi.

• Yanıta Yeni Alanların Eklenmesi: HTTP yanıt gövdesine yeni veri alanlarının dahil edilmesi (Postel's Law / Robustness Principle uyarınca, iyi tasarlanmış istemciler bilmedikleri ek alanları yoksaymalıdır).

• Performans ve Hata Düzeltmeleri: API'nin girdi-çıktı sözleşmesini bozmayan, veritabanı indekslemesi veya kod optimizasyonu gibi arka plan iyileştirmeleri.

API Versioning Nasıl Yapılır? Endüstri Standartları ve Yöntemler

API sürümleme sürecinde endüstri tarafından kabul görmüş dört temel yöntem bulunmaktadır. Her yöntemin kendine özgü mimari avantajları, dezavantajları, önbellekleme (caching) dinamikleri ve geliştirici deneyimi (developer experience - DX) etkileri vardır.

1. URI (URL) Yolu ile Versiyonlama

URI tabanlı sürümleme, sürüm bilgisinin doğrudan URL yolunun içine yerleştirildiği yaklaşımdır. Sektörde en yaygın kullanılan ve en kolay anlaşılır yöntemdir. Google, Facebook ve GitHub (eski sürümlerinde) bu yöntemi tercih etmiştir.

Örnek İstek:

GET https://api.yazilimfirmasi.com/v1/users
GET https://api.yazilimfirmasi.com/v2/users

Teknik Altyapı ve Yönlendirme:
URI tabanlı versiyonlamada yönlendirme (routing) genellikle API Gateway (Kong, Apigee, AWS API Gateway) veya tersine vekil sunucu (Nginx, HAProxy) katmanında çözülür. Gelen istek doğrudan /v1/ veya /v2/ prefix'ine göre arkadaki ilgili mikroservis pod'una yönlendirilir.

# Nginx ile URI Sürüm Yönlendirme Örneği
location /v1/ {
    proxy_pass http://user_service_v1;
}
location /v2/ {
    proxy_pass http://user_service_v2;
}

• Avantajları: Entegre eden geliştirici için son derece şeffaftır. Tarayıcı üzerinden doğrudan test edilebilir. CDN (Content Delivery Network) ve HTTP önbellekleme mekanizmaları ile kusursuz çalışır; çünkü URL değiştiğinde önbellek otomatik olarak geçersiz kalır.

• Dezavantajları: REST ilkelerine tam olarak uymaz. REST felsefesine göre bir URI, kaynağın benzersiz kimliğini (identity) temsil etmelidir; sürüm değiştikçe kaynağın kendisi değişmediği için URI'nin değişmemesi gerektiği savunulur.

2. Query (Sorgu) Parametresi ile Versiyonlama

Sürüm bilgisinin URL'nin sonuna bir sorgu parametresi olarak eklendiği yöntemdir. Microsoft, Amazon ve bazı Salesforce API'lerinde bu yaklaşıma rastlanır.

Örnek İstek:

GET https://api.yazilimfirmasi.com/users?api-version=2.0

Teknik Altyapı ve Kodlama:
Uygulama kodunda yönlendirme, gelen sorgu parametresinin parse edilmesiyle yapılır. Çoğu modern framework (NestJS, ASP.NET Core, Spring Boot) sorgu parametresine göre controller seviyesinde otomatik yönlendirme desteği sunar.

• Avantajları: Temel URI yapısı temiz kalır (/users). Varsayılan bir sürüm belirlemek (örneğin parametre gönderilmediğinde v1 kabul etmek) son derece kolaydır.

• Dezavantajları: Karmaşık sorgu parametreleri kullanan endpoint'lerde (filtreleme, sıralama vb.) URL okunabilirliğini zorlaştırır. Bazı agresif CDN ve proxy yapılandırmaları sorgu parametrelerini yok sayarak önbellekleme yapabilir; bu da eski sürüm yanıtının yeni sürüm isteyen kullanıcıya dönmesine (cache poisoning benzeri sorunlara) yol açabilir.

3. Custom Header (Özel Başlık) Kullanarak Versiyonlama

Sürüm bilgisinin HTTP istek başlıkları (headers) içerisine yerleştirildiği yöntemdir. Stripe bu yöntemin en başarılı uygulayıcılarından biridir.

Örnek İstek:

GET /users HTTP/1.1
Host: api.yazilimfirmasi.com
X-API-Version: 2026-08-28

Teknik Altyapı ve Vary Yönetimi:
Sunucu tarafında bu sürüm bilgisi HTTP istek başlıklarından okunur. Önbellekleme mekanizmalarının doğru çalışması için sunucunun mutlaka Vary başlığı dönmesi gerekir.

HTTP/1.1 200 OK
Content-Type: application/json
Vary: X-API-Version

Vary: X-API-Version tanımı, aracı proxy ve CDN sunucularına, aynı URL'ye giden isteklerin yanıttaki X-API-Version başlığına göre farklı önbellek hücrelerinde saklanması gerektiğini bildirir.

• Avantajları: URL'ler tamamen temiz ve standart kalır. Sürüm geçişleri, istemci tarafında URL değiştirmeden sadece HTTP istemci konfigürasyonunda tek bir satır güncellenerek yapılabilir.

• Dezavantajları: Tarayıcı üzerinden doğrudan çağrılarak test edilmesi zordur (Postman, cURL gibi araçlar gerektirir). Vary başlığı doğru yapılandırılmadığında ciddi önbellek karmaşalarına ve veri sızıntılarına yol açabilir.

4. Content Negotiation (Accept Header / Medya Türü) Yöntemi

REST mimarisinin kurucusu Roy Fielding tarafından en "saf" REST yöntemi olarak kabul edilen yaklaşımdır. Sürüm bilgisi, istemcinin sunucudan beklediği veri formatını belirttiği Accept başlığı içine gömülür.

Örnek İstek:

GET /users HTTP/1.1
Host: api.yazilimfirmasi.com
Accept: application/vnd.yazilimfirmasi.v2+json

Teknik Altyapı ve MediaType Eşlemesi:
Sunucu, gelen Accept başlığındaki MIME tipini ayrıştırır (content negotiation) ve uygun serialization (serileştirme) işlemini gerçekleştirerek yanıt döner.

• Avantajları: Kaynak odaklı (resource-oriented) tasarıma tam uyum sağlar. Aynı URI üzerinden kaynağın farklı sunum biçimleri (representation) yönetilmiş olur.

• Dezavantajları: Öğrenme eğrisi ve uygulama zorluğu en yüksek yöntemdir. İstek başlıklarının karmaşık yapısı, üçüncü parti geliştiricilerin API'yi entegre etmesini zorlaştırabilir. API Gateway seviyesinde routing kuralları yazmayı karmaşıklaştırır.

Hangi API Versiyonlama Yöntemini Seçmelisiniz? (Karşılaştırma)

Farklı API sürümleme yöntemlerinin kurumsal projelerdeki uygulanabilirliğini ölçmek adına, teknik parametreler üzerinden detaylı bir karşılaştırma yapmak gerekmektedir. Aşağıdaki tablo, mimari karar süreçlerinde rehberlik edecek temel kriterleri içermektedir:

Karar Verme Algoritması:

1. Halka Açık (Public) ve Geniş Katılımlı API'ler: Geliştiricilerin entegrasyon sürecini kısaltmak ve dokümantasyon takibini kolaylaştırmak için URI Tabanlı Versiyonlama en güvenli limandır.

2. SaaS ve Finansal Altyapı Sistemleri: İstemci tarafındaki güncellemelerin hassas olduğu ve URL yapısının değişmemesi gereken senaryolarda, geriye dönük uyumluluk güvencesi sunan Custom Header (Date-Based) yöntemi (Stripe modeli) tercih edilmelidir.

3. İç (Internal) Mikroservis Haberleşmeleri: Şirket içi servislerin birbirleriyle iletişiminde, REST mimarisinin getirdiği esnekliklerden tam yararlanmak adına Content Negotiation kullanılabilir.

API Yaşam Döngüsü: Eski Sürümleri Kullanımdan Kaldırma (Deprecation)

Bir API sürümünü sonsuza kadar desteklemek, yazılım ekipleri üzerinde ciddi bir bakım maliyeti (maintenance cost), teknik borç (technical debt) ve güvenlik riski oluşturur. Bu nedenle, her API sürümünün bir yaşam döngüsü olmalı ve eski sürümler planlı bir şekilde kullanımdan kaldırılmalıdır (deprecation ve sunset süreci).

İstemcileri Bilgilendirme ve Geçiş Süreci Yönetimi

Eski bir API sürümünü kapatmadan önce, o sürümü kullanan istemcilerin tespit edilmesi gerekir. API Gateway logları ve APM (Application Performance Monitoring) araçları analiz edilerek, hangi istemcinin (API Key veya IP tabanlı) hala v1 sürümüne istek attığı belirlenmelidir.

1. Erken Duyuru (Deprecation State): Sürümün artık desteklenmeyeceği ancak çalışmaya devam edeceği resmi olarak duyurulur. Geliştirici portalında, e-posta bültenlerinde ve API yanıt başlıklarında bu durum belirtilir.

2. Yavaşlatma ve Kısıtlama (Brownout Tests): Kapatma tarihinden birkaç hafta önce, eski sürüme yapılan isteklere kasıtlı olarak kısa süreli gecikmeler (latency injection) eklenir veya günün belirli saatlerinde API geçici olarak kapatılır (örneğin 15 dakikalık kesintiler). Bu işlem, pasif durumdaki geliştiricilerin sistemlerindeki hataları fark edip yeni sürüme geçmelerini tetikler.

3. Tamamen Kapatma (Sunset State): Belirlenen tarihte eski sürüm tamamen kapatılır ve bu adrese gelen isteklere 410 Gone HTTP durum kodu dönülür.

Sunset Başlığı (Sunset Header) Kullanımı

IETF (Internet Engineering Task Force) tarafından tanımlanan RFC 8594 standardı, bir API endpoint'inin ne zaman kapatılacağını makine tarafından okunabilir (machine-readable) bir şekilde bildirmek için Sunset HTTP başlığının kullanılmasını önerir.

Örnek Bir Deprecation ve Sunset Yanıtı:

HTTP/1.1 200 OK
Content-Type: application/json
Deprecation: @1771142400
Sunset: Tue, 10 Feb 2026 23:59:59 GMT
Link: <https://api.yazilimfirmasi.com/v2/users>; rel="successor-version"

Bu yanıtta:

• Deprecation başlığı, bu sürümün amortisman sürecine girdiğini gösterir (tarih Unix timestamp veya true/false olabilir).

• Sunset başlığı, sürümün tamamen kapatılacağı kesin tarihi (RFC 1123 formatında) belirtir.

• Link başlığı, istemcinin geçiş yapması gereken yeni API sürümünün dökümantasyon adresini işaret eder.

Kurumsal Projeler İçin API Versiyonlama En İyi Uygulamaları (Best Practices)

Büyük ölçekli kurumsal projelerde API sürüm yönetiminin sürdürülebilir olması için belirli standartların geliştirme sürecinin ilk gününden itibaren uygulanması gerekir.

SemVer (Semantic Versioning) İlkelerinin API'lere Uyarlanması

Yazılım paketlerinde kullanılan MAJOR.MINOR.PATCH (Örn: 1.0.0) biçimindeki SemVer standardı, web API'lerine doğrudan uygulandığında bazı farklılıklar gösterir. HTTP protokolü seviyesinde istemciler genellikle sadece kırıcı değişikliklerle (Major) ilgilenir.

• Major (Ana Sürüm): Kırıcı değişiklikler yapıldığında artırılır (1.0.0 -> 2.0.0).

• Minor (Alt Sürüm): Geriye dönük uyumlu yeni özellikler eklendiğinde artırılır. Genellikle URL'de gösterilmez, ancak dökümantasyonda ve iç takip sistemlerinde kayıt altına alınır.

• Patch (Yama): Geriye dönük uyumlu hata düzeltmeleri yapıldığında artırılır. İstemci tarafında hiçbir etkisi yoktur.

Kurumsal API tasarımlarında URL'de majör sürümün tutulması (/v1), minör ve patch sürümlerinin ise arka planda otomatik olarak yönetilmesi en sağlıklı yaklaşımdır.

API Gateway Katmanından Yararlanın

Yönlendirme mantığını (routing logic) uygulama kodunun içerisine yazmak, monolitik veya mikroservis kod tabanını (codebase) kirletir. Sürüm yönlendirme kararlarını uygulama katmanına ulaşmadan önce API Gateway (örneğin Kong, Apigee, AWS API Gateway veya Traefik) üzerinde çözün. Bu sayede, /v1/ isteği arka planda koşan v1 Kubernetes pod'una giderken, /v2/ isteği sıfır kesintiyle v2 pod'una yönlendirilebilir.

Otomatik Sözleşme Testleri (Contract Testing) ve CI/CD

Geriye dönük uyumluluğun kazara bozulmasını önlemek için CI/CD hatlarınıza (pipeline) otomatik sözleşme testleri entegre edin. Pact veya Spring Cloud Contract gibi araçlar kullanarak, servis sağlayıcının yaptığı bir değişikliğin mevcut istemci sözleşmelerini bozup bozmadığını kod daha production ortamına çıkmadan tespit edebilirsiniz. Ayrıca, OpenAPI/Swagger dökümanlarının her derlemede (build) otomatik olarak üretilmesi ve sürümlere göre ayrıştırılması (OAS v1, OAS v2) dökümantasyon güncelliğini garanti altına alır.