API Versioning Nedir? Eski İstemcileri Bozmadan API Nasıl Güncellenir?

Bir API yayınlandıktan sonra yalnızca sunucu ekibine ait olmaktan çıkar. Mobil uygulamalar, partner sistemleri, entegrasyon servisleri ve müşterilerin kendi yazılımları bu sözleşmeye bağlanır. Alan adını değiştirmek, bir response alanını kaldırmak veya hata kodunun anlamını değiştirmek sunucuda küçük bir düzenleme gibi görünse de eski istemcilerde üretim hatasına dönüşebilir.

API versioning, kırıcı değişiklikler gerektiğinde eski istemcilerin çalışmaya devam etmesini ve yeni istemcilerin kontrollü biçimde yeni sözleşmeye geçmesini sağlayan sürüm yönetimi yaklaşımıdır. Ancak her değişiklikte yeni bir v2 açmak da doğru değildir. Önce hangi değişikliklerin geriye uyumlu olduğu, hangilerinin mevcut istemci davranışını bozduğu belirlenmelidir.

Bu rehber genel API-first yaklaşımını tekrar etmez. Odak; versioning stratejileri, backward compatibility, breaking change, deprecation, sunset ve istemci geçiş operasyonudur.

API versioning nedir?

API versioning, aynı API ürününün farklı sözleşme sürümlerini tanımlama ve istemcilerin hangi sürümü kullandığını açık biçimde belirleme yöntemidir. Eski sürüm belirli süre çalışmaya devam ederken yeni sürüm farklı alan, davranış veya endpoint yapısı sunabilir.

Google’ın API Improvement Proposals dokümanı, API’lerin kullanıcılarla yapılan sözleşmeler olduğunu ve üretimde çalışan istemcilerin uyumluluğunun korunması gerektiğini vurgular Google AIP-180. API versioning dokümanı ise kararlı sürümlerde kırıcı değişiklikler için yeni major sürüm oluşturulmasını ele alır Google AIP-185.

Backward compatibility ne anlama gelir?

Backward compatibility, API’nin yeni halinde eski istemcilerin değişiklik yapmadan çalışmaya devam edebilmesidir. Yeni optional alan eklemek çoğu zaman uyumlu olabilir. Mevcut alanı kaldırmak, türünü değiştirmek veya zorunlu hale getirmek ise genellikle kırıcıdır.

Uyumluluk yalnızca JSON şemasından ibaret değildir. Aynı response alanı korunurken anlamı değiştirilirse istemci teknik olarak parse edebilir fakat yanlış iş sonucu üretir. Sıralama, pagination, varsayılan değer, hata kodu, yetki kapsamı ve rate limit davranışı da sözleşmenin parçasıdır.

Hangi değişiklikler genellikle geriye uyumludur?

• Response’a yeni ve optional alan eklemek.
• Yeni endpoint veya yeni HTTP metodu eklemek.
• Mevcut enum alanına istemcilerin bilinmeyen değerleri tolere ettiği durumda yeni değer eklemek.
• Yeni optional request parametresi eklemek.
• Dokümantasyonu ve örnekleri mevcut davranışı değiştirmeden geliştirmek.
• Performansı iyileştirirken response semantiğini korumak.
• Yeni hata ayrıntısı eklerken mevcut hata kodlarını korumak.

“Alan eklemek güvenlidir” varsayımı istemci kalitesine bağlıdır. Bazı istemciler bilinmeyen alanı reddedebilir veya enum değerlerini kapalı liste olarak işler. Bu nedenle API sözleşmesi, istemcilerin bilinmeyen alan ve değerleri nasıl ele alması gerektiğini açıkça belirtmelidir.

Hangi değişiklikler breaking change sayılır?

API sürümü URL içinde nasıl gösterilir?

URL path versioning en görünür yöntemdir: /v1/orders ve /v2/orders. Dokümantasyon, routing, log analizi ve gateway politikaları açısından anlaşılması kolaydır. İstemci hangi sürümü kullandığını URL’den açıkça görür.

Dezavantajı, sürümün kaynak adresine eklenmesi ve bütün endpoint’lerde tekrar edilmesidir. Küçük değişikliklerde yeni path açmak API yüzeyini hızla büyütebilir. Yine de dış geliştiricilere sunulan REST API’lerde sadeliği nedeniyle yaygın bir tercihtir.

Query parameter ile versioning nasıl çalışır?

İstemci /orders?api-version=2026-07-01 veya ?version=2 gibi parametre gönderir. Azure servislerinde tarih veya sürüm parametresiyle API davranışının seçildiği örnekler bulunur. Microsoft, Azure API Management içinde versioning şemalarının path, header veya query üzerinden tanımlanabileceğini açıklar Azure API Management Versions.

Query versioning mevcut kaynak URL’sini korur; fakat cache key, proxy yapılandırması ve dokümantasyon doğru hazırlanmalıdır. Parametre atlandığında hangi sürümün kullanılacağı belirsiz bırakılmamalıdır.

Header ile versioning ne zaman anlamlıdır?

Sürüm özel bir header veya medya türü içinde gönderilebilir. Böylece kaynak URL’si değişmez ve içerik pazarlığına benzer yapı kurulabilir. Ancak tarayıcı, debug, curl örneği ve manuel test açısından path kadar görünür değildir.

Header tabanlı model seçilecekse header adı, varsayılan sürüm, cache davranışı ve gateway yönlendirmesi standartlaştırılmalıdır. İstemcinin header göndermeyi unutması sessizce yanlış sürüme düşmemelidir.

Tarih tabanlı API sürümleme nedir?

Tarih tabanlı versioning, sürümü 2026-07-01 gibi yayın tarihiyle tanımlar. İstemci hangi sözleşme tarihine bağlı olduğunu açıkça belirtir. Bu yöntem sık yayın yapan platformlarda semantik v1, v2 adlarından daha ayrıntılı kontrol sağlayabilir.

Stripe, API sürümlerini tarih ve release adıyla yönetir; istemcilerin yeni sürümü test edip kontrollü yükseltmesini sağlar Stripe API Versioning. Stripe’ın sürüm politikası, aylık uyumlu değişiklikler ve belirli dönemlerde kırıcı sürüm aileleri yayınlama modelini açıklar Stripe Versioning Policy.

Hangi versioning stratejisi seçilmelidir?

Teknik olarak mümkün olan yöntemden çok geliştirici deneyimi ve operasyon kapasitesi önemlidir. API entegrasyon hizmeti planlanırken istemcilerin sürümü nasıl seçeceği, nasıl test edeceği ve nasıl yükselteceği birlikte tasarlanmalıdır.

Yeni sürüm ne zaman açılmalıdır?

Yeni major sürüm, mevcut sözleşmeyi koruyarak uygulanamayan kırıcı değişikliklerde açılmalıdır. Bir alanın yeniden adlandırılması, response modelinin kökten değişmesi, authentication akışının yenilenmesi veya resource yapısının bölünmesi buna örnektir.

Her özellik için yeni sürüm açmak destek maliyetini büyütür. Uyumlu eklemeler aynı sürüm içinde yayınlanabilir. Yeni sürüm kararı için önce adapter, yeni optional alan, yeni endpoint veya feature flag ile geçişin mümkün olup olmadığı değerlendirilmelidir.

Eski ve yeni sürüm aynı kod tabanında nasıl yönetilir?

En riskli yaklaşım, v1 ve v2 için bütün uygulamayı kopyalamaktır. Kopyalar zamanla farklılaşır, güvenlik düzeltmeleri bir sürümde unutulur ve bakım maliyeti artar. Daha sağlıklı modelde ortak domain ve iş kuralları korunur; sürüme özel request/response adapter’ları dış sınırda yer alır.

• Domain modelini sürüm DTO’larından ayırın.
• V1 ve v2 request modellerini ayrı doğrulayın.
• Ortak use case’leri mümkün olduğunca paylaşın.
• Response dönüşümünü sürüm adapter’ında yapın.
• Sürüme özel davranışı açık ve test edilebilir tutun.
• Güvenlik ve hata düzeltmelerini desteklenen bütün sürümlere uygulayın.

Deprecation nedir?

Deprecation, bir API sürümü, endpoint veya alanın artık yeni entegrasyonlar için önerilmediğini; fakat henüz çalışmaya devam ettiğini belirtir. Amaç istemcilere alternatif sunmak ve geçiş için zaman tanımaktır. Deprecation davranışı aniden değiştirmemelidir.

RFC 9745, HTTP response içinde bir kaynağın deprecated olduğunu bildiren Deprecation header alanını ve ek dokümana bağlanan link relation’ını tanımlar RFC 9745. Bu sinyal runtime seviyesinde görünürlük sağlar; ancak e-posta, dashboard ve dokümantasyon iletişiminin yerine geçmez.

Sunset nedir?

Sunset, eski sürümün hizmet vermeyi bırakacağı planlanan tarihi ifade eder. RFC 8594, bir URI’nin gelecekte erişilemez hale gelebileceği zamanı bildirmek için Sunset HTTP header alanını tanımlar RFC 8594.

Deprecation “artık kullanmayın” mesajıdır; sunset ise “şu tarihten sonra çalışmayacak” bilgisidir. Sunset tarihi gerçekçi destek kapasitesine, sözleşmelere, kritik istemcilere ve geçiş karmaşıklığına göre belirlenmelidir.

Eski istemciler nasıl tespit edilir?

Geçiş planının ilk adımı hangi istemcinin hangi sürümü kullandığını bilmektir. API key, OAuth client, tenant, SDK user-agent ve sürüm bilgisi loglarda ilişkilendirilmelidir. Yalnızca toplam v1 trafik oranı yeterli değildir; kalan çağrıların kritik müşteri veya terk edilmiş bir cron job’a ait olup olmadığı bilinmelidir.

• Sürüm bazında istek ve aktif istemci sayısını ölçün.
• Son kullanım tarihini istemci bazında kaydedin.
• Deprecated endpoint kullanımını ayrı raporlayın.
• 4xx ve 5xx oranlarını sürüm bazında izleyin.
• İletişim sorumlusu olmayan API key’leri belirleyin.
• Mobil uygulama sürümü ile API sürümünü ilişkilendirin.

İstemci geçiş planı nasıl hazırlanır?

1. Yeni sürüm ve kırıcı değişiklik listesini yayınlayın.
2. Eski davranış ile yeni davranış için migration guide hazırlayın.
3. Test veya sandbox ortamını erişime açın.
4. SDK ve örnek kodları yeni sürüme uyarlayın.
5. Deprecation tarihini ve destek kapsamını duyurun.
6. Aktif istemcileri kullanım verisine göre doğrudan bilgilendirin.
7. Geçiş ilerlemesini dashboard ve raporlarla takip edin.
8. Sunset öncesi uyarı sıklığını kademeli artırın.
9. Kritik müşteriler için teknik geçiş desteği sağlayın.
10. Sunset sonrasında kontrollü hata cevabı ve dokümantasyon bağlantısı sunun.

Mobil uygulamalarda versioning neden daha zordur?

Web istemcisi sunucuyla birlikte anında güncellenebilir; mobil uygulama ise mağaza incelemesi, kullanıcı güncelleme davranışı ve eski cihazlar nedeniyle aylarca eski sürümde kalabilir. API ekibi yalnızca en yeni mobil sürümü desteklediğini varsaymamalıdır.

Mobil istemci sürümü, minimum desteklenen uygulama sürümü ve API sürümü ayrı kavramlardır. Kritik güvenlik durumunda zorunlu uygulama güncellemesi gerekebilir; normal API geçişinde ise eski uygulamanın belirlenen süre çalışması planlanmalıdır.

Webhook sürümleri nasıl yönetilmelidir?

Webhook endpoint’i API’nin request-response çağrısından farklı yaşam döngüsüne sahip olabilir. Sağlayıcı yeni event alanları veya davranışı yayınladığında mevcut webhook handler bozulabilir. Her webhook endpoint’inin bağlı olduğu event/API sürümü açıkça kaydedilmelidir.

Yeni sürüm test endpoint’inde doğrulanmalı; event şemaları fixture ve contract testlerle sınanmalıdır. Eski ve yeni webhook sürümleri kısa süre paralel işlenebilir, ancak aynı iş olayının iki kez yan etki üretmemesi için event kimliği ve idempotency korunmalıdır.

Contract testing neden önemlidir?

Unit test sunucunun kendi kodunu doğrular; consumer-driven contract test ise gerçek istemci beklentilerinin yeni API değişikliğinde korunup korunmadığını kontrol eder. Response alanı, status code, enum ve hata şeması gibi sözleşme parçaları CI sürecinde karşılaştırılabilir.

OpenAPI şemaları arasında breaking change analizi yapılabilir. Ancak şema uyumlu görünürken semantik değişiklik oluşabileceği için kritik iş akışları entegrasyon testleriyle de doğrulanmalıdır. yazılım geliştirme sürecinde versioning kontrolü release öncesi otomatik kapı haline getirilmelidir.

En sık yapılan API versioning hataları

1. Her küçük özellik için yeni major sürüm açmak.
2. Kırıcı değişikliği aynı sürüm altında sessizce yayınlamak.
3. Varsayılan sürümü haber vermeden değiştirmek.
4. Eski ve yeni sürüm kodunu tamamen kopyalamak.
5. Deprecated alanı kaldırmadan önce gerçek kullanımını ölçmemek.
6. Migration guide yerine yalnızca changelog yayınlamak.
7. Mobil ve webhook istemcilerinin yavaş geçişini hesaba katmamak.
8. Sunset tarihini teknik ve ticari paydaşlarla doğrulamamak.
9. Eski sürümlere güvenlik düzeltmesi politikasını tanımlamamak.
10. Sürüm seçimini log ve metriklerde görünür kılmamak.

API versioning kontrol listesi

1. Değişiklik gerçekten kırıcı mı, yoksa uyumlu biçimde eklenebilir mi?
2. İstemci sürümü URL, query, header veya hesap ayarıyla açıkça seçiliyor mu?
3. Varsayılan sürüm davranışı belgeli mi?
4. Eski ve yeni sözleşmeler otomatik contract testlerden geçiyor mu?
5. Her sürümün destek ve güvenlik düzeltme süresi belirli mi?
6. Deprecated endpoint kullanımı istemci bazında ölçülüyor mu?
7. Migration guide, SDK ve sandbox hazır mı?
8. Deprecation ve sunset sinyalleri runtime ve iletişim kanallarında veriliyor mu?
9. Mobil uygulama ve webhook geçiş süresi hesaba katıldı mı?
10. Sunset sonrası hata cevabı ve destek yönlendirmesi planlandı mı?

Sonuç: API sürümü teknik etiket değil, destek sözleşmesidir

API versioning, eski istemcileri korurken ürünün gelişmesini sağlar. Sağlıklı yaklaşım, uyumlu değişiklikleri mevcut sürümde yayınlamak; gerçekten kırıcı değişikliklerde yeni sürüm oluşturmak ve eski sürümü ölçülebilir bir geçiş planıyla kapatmaktır.

URL, query, header veya tarih tabanlı yöntemlerden hangisi seçilirse seçilsin asıl kalite; backward compatibility kuralları, istemci görünürlüğü, contract testleri, deprecation iletişimi ve gerçekçi sunset politikasında ortaya çıkar. Sürüm yönetimi yalnızca routing değil, uzun vadeli entegrasyon güvenidir.