API Versiyonlama ve Geriye Dönük Uyumluluk Nasıl Yönetilir?

API versiyonlama, bir API’de yapılan değişikliğin mevcut istemcilerin çalışmasını bozup bozmayacağına göre planlanmalıdır. Yeni bir alanı opsiyonel olarak eklemek çoğu durumda geriye dönük uyumluluğu koruyabilirken; alan silmek, veri tipini değiştirmek veya aynı endpoint’in iş anlamını farklılaştırmak breaking change riski taşır.

Karar verirken yalnızca endpoint koduna bakmak yeterli değildir. İstemcilerin beklediği JSON yapısı, doğrulama kuralları, HTTP durum kodları, hata yanıtları, sıralama ve sayfalama davranışı birlikte değerlendirilmelidir. Bu yaklaşım, özellikle Python veya Java ile backend geliştiren ekiplerin API değişikliklerini daha kontrollü yönetmesine yardımcı olur.

API Versiyonlama Hangi Değişikliklerde Gerekli Olur?

Bir API’yi versiyonlamadan önce şu temel soruyu sormalısınız: Mevcut istemci, yeni sunucu sürümüyle aynı isteği gönderip aynı yanıtı doğru biçimde yorumlayabilecek mi? Cevap hayırsa veya bu konuda belirsizlik varsa, değişiklik yeni bir API versiyonu, uyumluluk katmanı ya da kontrollü bir geçiş süreci gerektirebilir.

Buradaki “istemci” yalnızca mobil uygulama anlamına gelmez. Bir web arayüzü, başka bir backend servisi, mobil uygulama, üçüncü taraf entegrasyon, otomasyon betiği veya öğrencinin yazdığı küçük bir Python programı da API istemcisi olabilir. Bu istemcilerin kaynak koduna müdahale edemiyorsanız, sunucu tarafında yaptığınız küçük bir değişiklik beklenmedik sonuçlar doğurabilir.

API tasarımının temel sözleşmesini öğrenmek isteyenler, konuyu backend geliştirme pratiğiyle birlikte ele almak için canlı sınıflı yazılım eğitimlerini inceleyebilir. Ancak versiyonlama kararı, kullanılan eğitim veya framework’ten bağımsız olarak istemci etkisi ve bakım maliyeti üzerinden verilmelidir.

Yeni bir alan eklemek ne zaman uyumlu sayılabilir?

Mevcut JSON yanıtına yeni ve opsiyonel bir alan eklemek, çoğu istemci için görece güvenli bir değişikliktir. Örneğin istemci yalnızca id ve name alanlarını okuyorsa, sunucunun yanıtına created_at alanının eklenmesi bu istemcinin mevcut işleyişini doğrudan bozmayabilir.

{
  "id": 42,
  "name": "Ada Lovelace",
  "created_at": "2026-08-29T10:30:00Z"
}

Bu yaklaşımın güvenli olabilmesi için istemcinin bilmediği alanları yok sayması gerekir. İstemci, gelen JSON yanıtının yalnızca önceden tanımlanmış alanlardan oluşmasını bekliyorsa veya şema doğrulaması sırasında bilinmeyen alanları hata kabul ediyorsa, yeni alan eklemek yine sorun yaratabilir.

Bu nedenle “yeni alan eklemek her zaman güvenlidir” demek doğru değildir. Daha doğru ifade şudur: Yeni alan, istemcinin sözleşmesi bu alanı zorunlu olarak reddetmiyorsa genellikle daha düşük riskli bir değişikliktir.

Ayrıca yeni alanın zorunlu hale getirilmesiyle opsiyonel eklenmesi arasında önemli fark vardır. Yanıta yeni bir alan eklemek genellikle daha düşük risk taşırken, istemciden yeni bir alan göndermesini zorunlu istemek mevcut istemcilerin isteklerini geçersiz hale getirebilir.

Alan silmek veya yeniden adlandırmak neden risklidir?

Bir alanı yanıt gövdesinden kaldırmak, o alanı kullanan tüm istemcilerde hata oluşturabilir. Örneğin bir istemci ekranda username değerini gösteriyorsa ve API bu alanı tamamen kaldırıp yerine display_name gönderiyorsa, istemci artık beklediği veriyi bulamayabilir.

Aynı sorun alan yeniden adlandırıldığında da ortaya çıkar. Teknik olarak iki alanın taşıdığı bilgi aynı olabilir; fakat istemci açısından alan adı API sözleşmesinin bir parçasıdır. Bu yüzden yeniden adlandırma çoğu durumda breaking change olarak değerlendirilmelidir.

Daha güvenli bir geçiş için eski alan bir süre korunabilir ve yeni alan ek olarak sunulabilir:

{
  "username": "ada",
  "display_name": "Ada Lovelace"
}

Bu yöntemde eski istemciler username alanını kullanmaya devam ederken güncellenen istemciler display_name alanına geçebilir. Ancak iki alanın aynı anlamı taşıdığı, hangisinin tercih edildiği ve eski alanın ne zaman kaldırılabileceği dokümantasyonda açıkça belirtilmelidir.

Veri tipini değiştirmek neden breaking change oluşturabilir?

Bir alanın veri tipini değiştirmek, alan adını korusanız bile istemcinin çalışma biçimini bozabilir. Örneğin başlangıçta string olarak dönen bir kullanıcı kimliğinin daha sonra integer olarak döndürülmesi bazı istemcilerde karşılaştırma, serileştirme veya doğrulama hatalarına yol açabilir.

// Önce
{ "user_id": "42" }

// Sonra
{ "user_id": 42 }

Bir istemci bu değeri doğrudan metinle birleştiriyor, belirli bir string formatını kontrol ediyor veya JSON şemasında string bekliyorsa yeni yanıtı işleyemeyebilir. Tersi yönde, sayısal bir değerin string’e dönüştürülmesi de aritmetik işlemler yapan istemcileri etkileyebilir.

Benzer risk tarih, para, durum kodu ve boolean değerlerinde de görülür. Örneğin true yerine "true" döndürmek, insan gözüyle benzer görünse de programlama dilleri açısından aynı veri değildir.

Aynı endpoint’in davranışını değiştirmek

Breaking change yalnızca JSON alanlarının değiştirilmesiyle oluşmaz. Endpoint aynı URL’ye sahip olsa bile işleyişi farklılaştırıldığında mevcut istemcilerin varsayımları bozulabilir.

• Başarılı bir isteğin artık farklı bir HTTP durum kodu döndürmesi,
• Sonuçların sıralama düzeninin değiştirilmesi,
• Varsayılan sayfalama limitinin değiştirilmesi,
• Bir filtre parametresinin anlamının değiştirilmesi,
• Daha önce kabul edilen bir değerin doğrulama nedeniyle reddedilmesi,
• Hata yanıtındaki alanların kaldırılması,
• Kimlik doğrulama gerektirmeyen bir endpoint’in farklı bir erişim kuralına bağlanması,
• Aynı isteğin iş kuralı açısından farklı bir işlem başlatması

Örneğin POST /orders endpoint’i başlangıçta sipariş oluştururken, daha sonra aynı istek gövdesiyle mevcut siparişi güncellemeye başlarsa sorun yalnızca teknik değil, işlevseldir. İstemci isteği başarıyla gönderebilir; fakat sunucunun yaptığı işlem değiştiği için veri bütünlüğü riske girebilir.

Bu tür değişikliklerde API versiyonlama, davranışın açık biçimde ayrıştırılmasını sağlar. Alternatif olarak yeni bir endpoint veya açık bir işlem parametresi kullanılabilir. Fakat aynı URL’nin sessizce farklı anlamlara gelmesi, hata ayıklamayı ve entegrasyon desteğini zorlaştırır.

Doğrulama kuralları da API sözleşmesinin parçasıdır

Bir alanın adı ve veri tipi aynı kalsa bile doğrulama kurallarını sıkılaştırmak mevcut istemcileri etkileyebilir. Örneğin daha önce 3 karakterlik kullanıcı adlarını kabul eden bir endpoint’in artık en az 8 karakter istemesi, API kodunda küçük bir değişiklik gibi görünür. Fakat eski istemcinin geçerli kabul edilen isteği artık reddedilir.

Aşağıdaki değişiklikler bu nedenle dikkatle değerlendirilmelidir:

• Bir alanın minimum veya maksimum uzunluğunu değiştirmek,
• Kabul edilen enum değerlerinden birini kaldırmak,
• Ondalık değerleri kabul etmemeye başlamak,
• Boş veya eksik alanları artık geçersiz saymak,
• Yeni bir bağımlı alan ilişkisi oluşturmak; örneğin country gönderildiyse city alanını da zorunlu kılmak.

Özellikle istemci sayısı bilinmiyorsa veya API dış ekipler tarafından kullanılıyorsa doğrulama değişiklikleri önce gözlemlenmeli, dokümante edilmeli ve mümkünse kademeli biçimde uygulanmalıdır. Bir değişikliğin mevcut istemcileri etkileyip etkilemediğini anlamak için yalnızca yeni testleri çalıştırmak yeterli değildir; eski istemcilerin istek örnekleriyle de geriye dönük test yapılmalıdır.

Hata yanıtları, sıralama ve sayfalama neden önemlidir?

İstemciler çoğu zaman yalnızca başarılı yanıtları değil, hata yanıtlarını da belirli bir yapıya göre işler. Örneğin istemci 400 durum kodunda message alanını okuyorsa, bu alanı kaldırıp yalnızca iç içe bir errors nesnesi göndermek istemcinin kullanıcıya hata gösterememesine neden olabilir.

Yeni hata ayrıntılarını eski yapıyı koruyarak eklemek daha uyumlu bir yaklaşım olabilir:

{
  "message": "Geçersiz istek",
  "errors": {
    "email": ["Geçerli bir e-posta adresi girin."]
  }
}

Benzer şekilde liste endpoint’lerinde sıralama ve sayfalama davranışı da sözleşmenin parçasıdır. Bir istemci ilk sayfada en yeni kayıtların geldiğini varsayıyorsa, varsayılan sıralamayı en eski kayıtlar olacak şekilde değiştirmek görünürde başarılı ama işlevsel olarak farklı bir sonuç üretir.

Sayfalama biçimini değiştirmek de risklidir. page ve limit kullanan bir istemcinin, sunucunun daha sonra yalnızca cursor tabanlı parametreleri kabul etmesiyle çalışmaması mümkündür. Bu nedenle sayfalama stratejisi, yanıt metadata’sı ve varsayılan limitler versiyonlama kararına dahil edilmelidir.

Geriye Dönük Uyumluluk ile Breaking Change Arasındaki Fark

Geriye dönük uyumluluk, mevcut istemcilerin sunucunun yeni sürümüyle çalışmaya devam edebilmesidir. İstemcinin kodu değiştirilmeden aynı istekleri göndermesi ve dönen yanıtları önceki anlamıyla yorumlayabilmesi beklenir. Breaking change ise bu varsayımlardan en az birinin bozulduğu değişikliktir.

Bu ayrımı yalnızca “kod hata verdi mi?” sorusuyla yapmak yetersizdir. Bir istemci teknik olarak hata vermeden de yanlış çalışabilir. Örneğin API aynı 200 durum kodunu döndürür, fakat dönen listenin sıralamasını değiştirirse kullanıcıya gösterilen sonuçlar beklenenden farklı olabilir.

İstemci sayısını ve değişikliğin operasyonel maliyetini hesaba katmak için yazılım geliştirme sürecinde video tabanlı eğitim içerikleriyle kendi hızınızda API testleri, JSON yapıları ve backend iş akışlarını tekrar edebilirsiniz. Buradaki amaç belirli bir framework’e bağlı kalmadan, değişikliklerin istemci sözleşmesine etkisini sistematik biçimde analiz etmektir.

Versiyon artırmadan yapılabilecek görece güvenli değişiklikler

Aşağıdaki değişiklikler, istemci sözleşmesinin temelini koruduğu sürece çoğu projede yeni bir ana API versiyonu gerektirmeyebilir:

• Mevcut alanların anlamını ve veri tipini koruyarak yeni bir opsiyonel alan eklemek,
• Yeni bir filtre veya sıralama parametresini opsiyonel kabul etmek,
• Mevcut hata yanıtı yapısını koruyup ek hata ayrıntıları sunmak,
• Yeni bir endpoint eklemek ve mevcut endpoint’lere dokunmamak,
• Sunucunun ek istek parametrelerini, eski istemciler göndermediğinde varsayılan davranışla kabul etmek,
• Mevcut değerlerin anlamını değiştirmeden dokümantasyonu geliştirmek.

Burada kritik nokta, yeni özelliğin eski istemci için zorunlu hale gelmemesidir. Örneğin include_details=true parametresinin opsiyonel eklenmesi uyumlu olabilir. Fakat sunucunun bu parametreyi her istekte zorunlu kılması, eski istemcilerin isteklerini geçersiz hale getirir.

Hangi değişiklikler breaking change olarak değerlendirilmelidir?

Şu değişiklikler genellikle yeni bir versiyon, yeni endpoint veya kontrollü geçiş planı gerektirir:

• İstemcinin göndermesi gereken yeni bir zorunlu alan eklemek,
• Yanıttaki bir alanı silmek veya yeniden adlandırmak,
• Bir alanın veri tipini değiştirmek,
• Başarı veya hata durumundaki HTTP durum kodunu değiştirmek,
• Kimlik doğrulama veya yetkilendirme akışını değiştirmek,
• Pagination parametrelerini veya yanıt metadata’sını değiştirmek,
• Bir enum değerini kaldırmak ya da mevcut bir değerin anlamını değiştirmek,
• Endpoint’in aynı isteğe farklı bir iş anlamı vermesi,
• Varsayılan sıralama veya filtreleme davranışını değiştirmek,
• Önceden kabul edilen istekleri yeni doğrulama kurallarıyla reddetmek.

Örneğin bir endpoint daha önce bulunamayan kayıt için 404 döndürürken artık 200 ile boş nesne döndürüyorsa, istemcinin kontrol akışı değişebilir. Bazı istemciler 404 durumunu “kayıt yok” olarak ele alıp yeni kayıt oluştururken, 200 yanıtını başarılı işlem kabul edip farklı bir kod yoluna girebilir.

Her değişiklikte kullanılacak kontrol sorusu

API değişikliğini yayınlamadan önce şu soruyu yazılı olarak yanıtlayın: Eski istemci bu yanıtı ve davranışı hâlâ doğru biçimde yorumlayabilir mi?

Bu soruyu aşağıdaki kontrol listesiyle somutlaştırabilirsiniz:

1. İstek gövdesindeki mevcut alanlar hâlâ aynı anlamı taşıyor mu?
2. Eski istemci yeni bir zorunlulukla karşılaşmadan isteğini gönderebiliyor mu?
3. Yanıttaki eski alanlar, veri tipleri ve temel yapı korunuyor mu?
4. HTTP durum kodları istemcinin beklediği akışla uyumlu mu?
5. Hata yanıtları eski istemcinin okuyabildiği yapıyı koruyor mu?
6. Sıralama, sayfalama, filtreleme ve varsayılan davranışlar değişti mi?
7. Aynı endpoint’in iş anlamı veya veri üzerindeki etkisi farklılaştı mı?
8. Kimlik doğrulama, yetkilendirme veya istek başlıkları açısından yeni bir zorunluluk oluştu mu?

Bu sorulardan herhangi birine “hayır” cevabı veriyorsanız değişikliği yalnızca küçük bir refactor olarak değerlendirmeyin. Önce eski istemciyle uyumlu bir alternatif tasarlayın; bu mümkün değilse versiyonlama, yeni endpoint veya deprecation süreci kullanarak geçiş planlayın.

URL, Header ve Media Type Versiyonlama Yöntemleri Nasıl Karşılaştırılır?

API versiyonlama yöntemleri aynı problemi farklı katmanlarda çözer: İstemci ile sunucu arasındaki sözleşmenin hangi sürümünün kullanılacağını belirtir. URL tabanlı versiyonlama sürümü adresin içinde görünür hâle getirirken, header tabanlı yaklaşım bilgiyi istek üstverisine taşır. Media type tabanlı versiyonlama ise istemcinin hangi temsil biçimini istediğini Accept veya gerektiğinde Content-Type üzerinden bildirir.

Bu yöntemlerden biri her proje için otomatik olarak doğru değildir. İstemci sayısı, istemcilerin ne kadarının sizin kontrolünüzde olduğu, sürüm bilgisinin loglarda ne kadar görünür olması gerektiği, arada gateway veya proxy bulunup bulunmadığı ve ekibin aynı anda kaç sözleşmeyi sürdürebileceği birlikte değerlendirilmelidir.

URL tabanlı versiyonlama nasıl çalışır?

URL tabanlı yöntemde sürüm bilgisi endpoint yoluna eklenir. En bilinen kullanım biçimi /v1/users ve /v2/users gibi ayrı adresler oluşturmaktır. İstemci, çağrı yaptığı URL üzerinden hangi API sözleşmesini kullandığını açıkça belirtir.

Bu yaklaşımın en güçlü yönü keşfedilebilirlik ve gözlemlenebilirliktir. Bir geliştirici dokümantasyona bakmadan URL’yi gördüğünde sürüm hakkında fikir edinebilir. Sunucu loglarında, hata kayıtlarında, erişim metriklerinde ve istek izleme ekranlarında sürüm bilgisi genellikle doğrudan görünür. Özellikle çok sayıda dış istemcinin bulunduğu entegrasyonlarda bu açıklık, hangi istemcilerin eski sürümde kaldığını anlamayı kolaylaştırır.

URL’nin değişmesi, önbellekleme ve yönlendirme katmanlarında da pratik bir ayrım oluşturabilir. Ancak bu, her cache altyapısının otomatik olarak doğru davrandığı anlamına gelmez. URL sürüm bilgisini içeriyor olsa bile farklı header’lara, kullanıcı yetkilerine veya sorgu parametrelerine göre değişen yanıtların cache anahtarında doğru biçimde ayrıştırılması gerekir.

Header tabanlı versiyonlama ne zaman tercih edilir?

Header tabanlı versiyonlamada endpoint URL’si sabit kalır; sürüm bilgisi özel bir header ile gönderilir. Örneğin istemci, Accept-Version: 2 benzeri bir header kullanarak sunucudan belirli bir sözleşmeyi isteyebilir. Kullanılacak header adı ve değer formatı, API sözleşmesinde açıkça tanımlanmalıdır.

Bu yöntemde URL yapısı sade kalır. Aynı kaynağın farklı sözleşmeleri tek bir endpoint adresi altında yönetilebilir. Özellikle istemci ve sunucu ekipleri birlikte çalışıyor, istemciler merkezi olarak güncellenebiliyor ve HTTP istek header’ları üzerinde yeterli kontrol bulunuyorsa kontrollü bir geçiş sağlanabilir.

Buna karşılık sürüm bilgisi URL’de görünmediği için günlük operasyonlarda ek dikkat gerekir. Loglama sistemi ilgili header’ı kaydetmiyorsa iki farklı sürümün istekleri aynı endpoint gibi görünebilir. Hata ayıklama sırasında yalnızca URL’ye bakmak da yeterli olmaz. Bu nedenle sürüm header’ının erişim loglarına, dağıtık izleme kayıtlarına ve hata raporlarına taşındığından emin olunmalıdır.

Header tabanlı bir tasarımda dokümantasyon da daha ayrıntılı hazırlanmalıdır. İstemci geliştiricisine yalnızca endpoint adresini vermek yeterli değildir; hangi header’ın zorunlu olduğu, header gönderilmezse hangi varsayılan sürümün kullanılacağı, desteklenen değerler ve geçersiz değerlerde alınacak hata yanıtı açıkça yazılmalıdır.

Media type tabanlı versiyonlama nasıl ayrışır?

Media type tabanlı versiyonlama, API’nin döndürdüğü veya kabul ettiği temsilin sürümünü HTTP içerik anlaşması üzerinden belirler. İstemci, Accept header’ında belirli bir media type göndererek istediği temsil biçimini ifade eder. Örneğin kavramsal olarak application/vnd.example.user-v2+json benzeri bir değer kullanılabilir.

Bu yöntemde sürüm, kaynağın adresinden çok kaynağın nasıl temsil edildiğiyle ilişkilendirilir. Aynı URL, farklı istemciler için farklı temsil sözleşmeleri sunabilir. Bu, URL’leri sabit tutmak isteyen ekipler için anlamlı olabilir. Fakat uygulama, gateway ve dokümantasyon katmanlarının media type değerlerini tutarlı biçimde işlemesi gerekir.

Media type yaklaşımının en önemli sınırı, sürüm bilgisinin URL’ye göre daha az görünür olmasıdır. Bir geliştirici yalnızca endpoint adresini gördüğünde hangi temsil sürümünün kullanıldığını anlayamayabilir. Ayrıca istemcinin Accept header’ını doğru göndermesi, sunucunun da bu tercihi doğru yorumlaması gerekir.

Content-Type ile Accept arasındaki rol de karıştırılmamalıdır. Content-Type çoğunlukla istemcinin sunucuya gönderdiği gövdenin biçimini belirtir. Accept ise istemcinin sunucudan hangi yanıt biçimini kabul etmek istediğini ifade eder. API sözleşmesinde bu iki header’ın hangi aşamada kullanılacağı ayrıca açıklanmalıdır.

Üç yöntemin karşılaştırması

Önbellekleme ve yanlış yanıt riskini nasıl azaltırsınız?

Versiyonlama yöntemi seçilirken yalnızca endpoint tasarımına bakmak yeterli değildir. Bir API yanıtı, sürüm bilgisi doğru dikkate alınmadan önbelleğe alınırsa istemciye başka bir sürüme ait yanıt dönebilir. Örneğin header tabanlı iki istek aynı URL’ye gönderilmiş olsa da biri v1, diğeri v2 sözleşmesini istiyor olabilir. Cache katmanı yalnızca URL’yi anahtar olarak kullanıyorsa bu iki yanıtı birbirinden ayıramayabilir.

Media type yaklaşımında benzer risk Accept header’ı için ortaya çıkar. Sunucu, aynı URL’ye gelen farklı Accept değerlerine göre farklı JSON temsilleri üretiyorsa bu ayrımın cache mantığında da korunması gerekir. URL tabanlı yöntemde sürüm ayrımı daha görünür olsa bile kimlik doğrulama, dil, sıkıştırma veya kullanıcıya özel veri gibi diğer değişkenler ayrıca değerlendirilmelidir.

Her yöntemde şu soruların yanıtı tasarım dokümanında yer almalıdır:

• Yanıt hangi girdilere göre değişiyor?
• Bu girdiler cache anahtarında nasıl temsil ediliyor?
• Cache’ten dönen yanıtın hangi API sürümüne ait olduğu nasıl doğrulanıyor?
• Yeni sürüm devreye alındığında eski yanıtların geçerlilik süresi nasıl yönetiliyor?
• Bir istemci yanlış veya eksik sürüm bilgisi gönderirse güvenli varsayılan davranış ne oluyor?

Dokümantasyonda her varyantı ayrı bir sözleşme olarak göstermek de önemlidir. Aynı endpoint adresinin farklı header veya media type değerleriyle farklı yanıtlar ürettiği bir sistemde örnek istekler, örnek yanıtlar, hata kodları ve alan değişiklikleri birlikte verilmelidir. Bu yaklaşım, Python temeliyle backend geliştirmeye başlayan bir öğrencinin yalnızca endpoint yazmasını değil, istemci-sunucu sözleşmesini düşünmesini de sağlar. Bu bakış açısını yapılandırılmış biçimde geliştirmek isteyenler için canlı sınıflı Python ve Java eğitimleri içinde temel programlama kararlarının backend senaryolarına bağlanması yararlı bir çalışma zemini oluşturabilir.

Hangi API Versiyonlama Yöntemini Seçmelisiniz?

API versiyonlama yöntemi seçerken “URL mi, header mı?” sorusunu tek başına sormak yerine, değişikliğin istemciler ve operasyon üzerindeki etkisini ölçmek gerekir. Sağlıklı karar; değişikliğin niteliği, istemcilerin kontrol düzeyi, entegrasyon sayısı, gözlemlenebilirlik ihtiyacı, altyapı katmanları ve aynı anda işletilecek sözleşme sayısı birlikte incelenerek verilir.

Karar sırasını altı soruyla kurun

1. Değişiklik mevcut istemcinin ayrıştırabileceği bir yanıt mı üretiyor?

   Yeni bir alanın yanıta eklenmesi, mevcut istemcinin bilmediği alanları yok sayması hâlinde uyumlu olabilir. Buna karşılık bir alanın türünü değiştirmek, mevcut alanı kaldırmak veya aynı alanın anlamını değiştirmek istemcinin ayrıştırma mantığını bozabilir. İlk karar noktası, değişikliğin teknik olarak mevcut sözleşme içinde taşınıp taşınamayacağıdır.

2. İstemciler üzerinde kontrolünüz var mı?

   Mobil uygulama, masaüstü yazılımı, kurum içi servis veya sizin yönettiğiniz frontend istemcilerinde geçiş takvimi daha kontrollü olabilir. Dış müşterilerin, iş ortaklarının veya farklı ekiplerin kullandığı bir API’de ise istemcilerin ne zaman güncelleneceğini siz belirleyemeyebilirsiniz.

3. Kaç farklı istemci ve entegrasyon etkilenebilir?

   İstemci sayısı arttıkça küçük bir sözleşme değişikliğinin destek talepleri, test senaryoları ve geçiş takibi üzerindeki maliyeti büyür. Az sayıda istemcide doğrudan iletişimle yürütülebilecek bir geçiş, çok sayıda dış istemcide aynı kolaylıkla yönetilemeyebilir.

4. Sürüm bilgisi log, dokümantasyon ve hata ayıklama süreçlerinde ne kadar görünür olmalı?

   Operasyon ekibinin bir isteğin hangi sözleşmeye ait olduğunu saniyeler içinde anlaması gerekiyorsa URL tabanlı ayrım pratik bir avantaj sağlar. Header veya media type kullanıldığında aynı görünürlüğü elde etmek için bu bilgileri loglara ve izleme sistemlerine bilinçli olarak eklemek gerekir.

5. Gateway, CDN ve önbellek katmanları hangi yöntemi daha güvenli taşıyor?

   Aradaki altyapı, sürüm bilgisinin bulunduğu katmanı doğru işleyebilmelidir. URL ayrımı kolay yönlendirilebilir görünse de header ve media type değerleriyle değişen yanıtların cache ve yönlendirme kurallarında hesaba katılması gerekir. Altyapı ekibinin bu davranışı nasıl test edeceği kararın bir parçasıdır.

6. Aynı anda kaç sözleşmeyi işletmek ekip için sürdürülebilir?

   Her yeni sürüm yalnızca yeni bir endpoint anlamına gelmez. Şema doğrulama, testler, dokümantasyon, örnek istemciler, hata kayıtları, izleme panelleri ve deprecation planı da güncellenir. Ekip iki veya daha fazla sürümü ne kadar süre destekleyebileceğini gerçek kapasitesine göre değerlendirmelidir.

Senaryo 1: Az sayıda ve kontrol edilen istemcide header geçişi

Bir ekip, kendi yönettiği birkaç backend servisi arasında API sözleşmesi kullanıyor olsun. İstemcilerin tamamı aynı ekip tarafından güncellenebiliyor ve dağıtım takvimi biliniyor. Yapılan değişiklik, yanıt temsilini farklılaştırıyor ancak endpoint adreslerinin sabit kalması operasyonel açıdan değer taşıyor.

Bu durumda header tabanlı veya media type tabanlı geçiş değerlendirilebilir. Sürüm bilgisi istekte açıkça taşınır, istemciler aynı URL üzerinden uygun sözleşmeyi seçer. Ancak bu kararın güvenli olabilmesi için şu kontroller yapılmalıdır:

• İstemci kütüphaneleri ilgili header’ı otomatik ve doğru biçimde göndermeli.
• Loglama sistemi sürüm header’ını istek kaydıyla birlikte saklamalı.
• Cache katmanı header veya media type farklılıklarını göz önünde bulundurmalı.
• Varsayılan sürüm davranışı açıkça tanımlanmalı; sessizce beklenmeyen sürüme düşülmemeli.
• Eski sözleşmeden yeni sözleşmeye geçiş için ölçülebilir bir bitiş koşulu belirlenmeli.

Senaryo 2: Çok sayıda dış istemcide görünür v1–v2 ayrımı

Bir API’nin farklı ekipler, müşteriler veya dış entegrasyonlar tarafından kullanıldığını düşünelim. İstemcilerin sürüm yükseltme takvimi birbirinden farklıdır ve bazı tüketiciler eski sözleşmeyi uzun süre kullanabilir. Böyle bir ortamda hangi istemcinin hangi sürümde olduğu, destek taleplerinde ve erişim kayıtlarında hızlı biçimde anlaşılmalıdır.

URL tabanlı /v1 ve /v2 ayrımı bu ihtiyaca görünür bir sınır sağlayabilir. Eski istemci mevcut adresinde çalışmaya devam ederken yeni istemci açıkça yeni endpoint’e geçebilir. Bu yaklaşım daha fazla endpoint, test ve dokümantasyon bakımı gerektirebilir; fakat sürümün istemci, gateway ve log katmanlarında fark edilmesini kolaylaştırır.

Seçimi basit bir karar matrisiyle netleştirin

Aşağıdaki çerçeve, tek başına otomatik seçim yapmaz; ekip içi tartışmayı somutlaştırır. Her satırda “yüksek” değer, ilgili ihtiyacın karar üzerindeki ağırlığının fazla olduğunu gösterir.

Son kararı verirken yalnızca geliştirici deneyimini değil, bakım kapasitesini de hesaba katın. Bir yöntem teorik olarak esnek olsa bile ekip header değerlerini izlemiyor, media type varyantlarını test etmiyor veya iki sözleşmenin dokümantasyonunu güncel tutamıyorsa pratikte riskli hâle gelebilir. Tersine, URL tabanlı yöntemin açık görünürlüğü, daha fazla endpoint yönetimini kabul edilebilir kılabilir.

Python veya Java temellerini backend kararlarına bağlayan öğrenme sürecinde de aynı yaklaşım geçerlidir: Önce sözleşmeyi, istemci etkisini ve hata durumlarını düşünmek; ardından framework içinde endpoint veya middleware kodunu yazmak. Bu nedenle versiyonlama, yalnızca Flask ya da başka bir araçta kullanılacak sözdizimini öğrenme konusu değil, sistem davranışını ve operasyonel maliyeti birlikte değerlendirme problemidir.

Deprecation Süreciyle Güvenli API Geçişi Nasıl Yönetilir?

Bir API sürümünü kullanımdan kaldırmak, eski endpoint’i aniden silmekten ibaret değildir. Güvenli bir geçişte amaç; mevcut istemcilerin çalışmaya devam etmesini sağlarken yeni sözleşmeye geçişi ölçülebilir, geri alınabilir ve iletişimi yapılmış bir süreç hâline getirmektir. Bunun için eski sürüm bir süre çalışır tutulmalı, hangi istemcilerin etkileneceği bilinmeli ve kapatma kararı yalnızca varsayıma değil gerçek kullanım verilerine dayanmalıdır.

Deprecation duyurusu da yalnızca “v1 şu tarihte kapanacaktır” cümlesinden oluşmamalıdır. Duyuruda etkilenen endpoint, yeni karşılığı, geçiş örneği, olası riskler, geçiş sırasında alınması gereken aksiyonlar ve iletişim kanalı birlikte verilmelidir. Böylece istemci geliştiricisi neyin değiştiğini, ne yapması gerektiğini ve sorun yaşadığında kime başvuracağını tek yerde görebilir.

1. Mevcut sözleşmeyi ve etkilenen istemcileri envanterleyin

İlk adım, hangi API sözleşmesinin değişeceğini ve bu sözleşmeyi hangi istemcilerin kullandığını ortaya çıkarmaktır. Sadece endpoint listesini çıkarmak yeterli değildir. İstemcilerin hangi sürümü, hangi endpoint’i, hangi kimlik doğrulama yöntemiyle ve hangi kullanım yoğunluğunda çağırdığı da incelenmelidir.

• Sözleşme envanteri: Endpoint’ler, HTTP metotları, istek parametreleri, yanıt alanları, hata kodları ve kimlik doğrulama davranışları listelenmelidir.
• İstemci envanteri: Web uygulamaları, mobil uygulamalar, arka plan görevleri, üçüncü taraf entegrasyonlar ve şirket içi servisler ayrıştırılmalıdır.
• Sahiplik bilgisi: Her istemci için sorumlu ekip veya iletişim kişisi belirlenmelidir.
• Kullanım gözlemi: İstek sayısı, hata oranı, son kullanım zamanı, kullanılan API sürümü ve istemci tanımlayıcısı izlenmelidir.

Bu aşamada sorumlu ekip genellikle API sahibi backend ekibidir; ancak istemci envanterinin doğrulanması için frontend, mobil, operasyon ve ürün ekiplerinden destek alınmalıdır. Ölçülebilir gözlem noktaları arasında sürüm bazında istek sayısı, istemci bazında son çağrı zamanı ve eski endpoint’i kullanan aktif entegrasyon sayısı bulunabilir.

Envanter eksikse geçiş planı tamamlanmış sayılmamalıdır. Bilinmeyen bir istemci, eski sürüm kapatıldığında beklenmeyen bir üretim hatasına dönüşebilir. Geri dönüş planı olarak eski endpoint’in silinmemesi, önce uyarı üretmesi veya yalnızca belirli istemciler için kontrollü kapatma uygulanması düşünülebilir.

2. Yeni sürümü ayrı ve açık bir sözleşme olarak tasarlayın

Yeni sürüm, eski yanıtın birkaç alanı değiştirilmiş hâli olarak değil, baştan tanımlanmış ayrı bir sözleşme olarak ele alınmalıdır. Hangi alanların korunduğu, hangilerinin yeniden adlandırıldığı, veri tiplerinin değişip değişmediği ve hata davranışının nasıl ilerlediği açıkça yazılmalıdır.

Örneğin v1 sürümünde kullanıcı adı doğrudan yanıtın içinde bulunuyorsa v2 sürümünde kullanıcı bilgilerinin profile nesnesi altında gruplanması istemci tarafında yeni bir okuma biçimi gerektirebilir. Bu değişiklik teknik olarak daha düzenli bir temsil sunsa bile eski istemci açısından breaking change olabilir. Bu nedenle yeni sürümün tasarımında yalnızca “daha temiz JSON” hedeflenmemeli; geçiş maliyeti de hesaba katılmalıdır.

• Alan adlarını değiştiriyorsanız eski alanın yeni karşılığını belirtin.
• Bir alanın veri tipini değiştiriyorsanız istemci üzerindeki dönüştürme etkisini açıklayın.
• Zorunlu hâle gelen yeni istek alanlarını açıkça işaretleyin.
• HTTP durum kodları ve hata gövdelerindeki değişiklikleri ayrı başlık altında belgeleyin.
• Sayfalama, sıralama, filtreleme ve tarih-saat biçimi gibi davranışsal farkları örneklerle gösterin.
• Yeni sürümde kaldırılan özellikler varsa bunların alternatifini belirtin.

Bu adımın sorumlusu API tasarımını yapan backend ekibidir. Gözlem noktası, eski ve yeni sözleşme arasındaki farkların makine tarafından veya manuel incelemeyle çıkarılmış olmasıdır. Geri dönüş planı ise yeni sürümdeki değişikliklerin beklenenden fazla istemciyi etkilemesi durumunda sözleşmeyi daraltmak, uyumluluk katmanı eklemek veya geçiş tarihini ertelemektir.

3. Duyuru ve migration dokümanını yayımlayın

Deprecation duyurusu, teknik ekiplerin karar almasını sağlayacak kadar somut olmalıdır. Duyuruda yalnızca bir son kullanım tarihi verilmesi, istemcilerin nasıl geçiş yapacağını belirsiz bırakır. İyi bir duyuru şu bilgileri içermelidir:

1. Kullanımdan kaldırılacak sürüm ve etkilenen endpoint’ler.
2. Yeni sürümdeki karşılık endpoint veya kaynak modeli.
3. Eski ve yeni istek-yanıt örnekleri.
4. Alan, durum kodu, doğrulama ve hata davranışı farkları.
5. İstemci geliştiricisinin uygulaması gereken geçiş adımları.
6. Geçiş sırasında görülebilecek riskler ve bilinen sınırlamalar.
7. Destek sonlandırma koşulları ve iletişim kanalı.
8. Sorun yaşanması hâlinde geri bildirim veya destek süreci.

Migration dokümanı, “v1 yerine v2 kullanın” demekten daha ileri gitmelidir. Örneğin bir istemcinin v1 yanıtındaki user_name alanını okuyup v2 yanıtındaki profile.name alanına geçmesi gerekiyorsa, bu dönüşüm doğrudan kod veya sözde kod örneğiyle gösterilmelidir. İstemci geliştiricisi, yalnızca kavramsal açıklamayla bırakılmamalıdır.

Duyurunun sorumlusu API sahibi ekip olabilir; fakat duyurunun görünür olduğu kanal, tüm etkilenen istemcileri kapsamalıdır. Bu kanal teknik dokümantasyon, geliştirici portalı, proje iletişim sistemi veya doğrudan entegrasyon sahiplerine gönderilen bildirim olabilir. Ölçülebilir gözlem noktaları; dokümanın görüntülenme durumu, destek taleplerinin konusu, migration örneklerinin test edilme oranı ve geri bildirim sayısıdır.

4. Geçiş döneminde eski sürümü çalışır tutun

Yeni sürüm yayımlandığı gün eski sürümü kapatmak, yalnızca tüm istemcilerin aynı ekip tarafından kontrol edildiği ve geçişin doğrulandığı sınırlı durumlarda düşünülebilir. Birden fazla ekip veya dış entegrasyon söz konusuysa eski sürümün belirli bir geçiş dönemi boyunca çalışır tutulması daha güvenlidir.

Bu dönemde eski sürümün sonsuza kadar destekleneceği izlenimi verilmemelidir. Eski endpoint’in yanıtında veya HTTP başlıklarında deprecation bilgisi gösterilebilir; ancak kullanılan yöntemin istemciler tarafından nasıl algılanacağı test edilmelidir. Uyarı üretmek, eski sürümü kapatmakla aynı şey değildir. Uyarıların log’larda görünmesi ve istemci sahiplerine ulaşması sağlanmalıdır.

Eski sürümün çalışır tutulması, yeni özelliklerin mutlaka eski sürüme de eklenmesi anlamına gelmez. Çoğu durumda v1 güvenlik ve kritik hata düzeltmeleriyle sınırlı tutulurken yeni işlevler yalnızca v2 üzerinde geliştirilebilir. Böylece iki sürümün bakım maliyeti kontrol altında tutulur.

• Eski sürüm için yalnızca kritik hata ve güvenlik düzeltmelerini kabul edin.
• Yeni özelliklerin hangi sürümde yayımlanacağını açıkça belirtin.
• v1 ve v2 için ayrı hata oranlarını izleyin.
• Eski sürümün trafik payını düzenli aralıklarla karşılaştırın.
• Geri dönüş için yönlendirme, feature flag veya önceki deployment paketini hazır tutun.

5. Trafik, hata, sürüm ve kullanım metriklerini izleyin

Bir sürümün ne zaman kapatılabileceği yalnızca takvimle belirlenmemelidir. Kullanım verileri, geçişin gerçekten gerçekleşip gerçekleşmediğini gösterir. En azından aşağıdaki metrikler sürüm bazında ayrıştırılmalıdır:

• Eski ve yeni sürüme gelen toplam istek sayısı.
• Başarılı istek oranı ve HTTP 4xx/5xx dağılımı.
• İstemci veya API anahtarı bazında v1 kullanım oranı.
• Endpoint bazında son çağrı zamanı.
• Yanıt gecikmesi ve zaman aşımı oranı.
• Yeni sürüme geçişten sonra oluşan destek talepleri.
• İstemci sürümü, platformu ve entegrasyon türüne göre hata dağılımı.

Bir istemci v1’i az kullanıyor görünse bile kritik bir iş akışında kullanıyor olabilir. Bu nedenle yalnızca toplam trafik oranına bakmak yeterli değildir. Düşük trafikli ama iş açısından kritik entegrasyonlar ayrıca değerlendirilmelidir. Sorumlu ekip, dashboard ve alarm eşiklerini belirlemeli; gözlem noktası olarak hem teknik başarısızlığı hem de iş akışı etkisini takip etmelidir.

Geri dönüş planı, hata oranı belirli bir eşik üzerine çıktığında yeni sürümdeki deployment’ı geri almayı veya trafiği geçici olarak eski sürüme yönlendirmeyi kapsayabilir. Ancak otomatik geri dönüş mekanizması, veri biçimi veya kalıcı veri migrasyonu gibi durumlarda tek başına yeterli olmayabilir. Bu nedenle geri dönüş planı yalnızca uygulama kodunu değil, veri ve konfigürasyon değişikliklerini de kapsamalıdır.

6. İstemcilerden doğrulama ve geri bildirim toplayın

İstemci tarafında geçişin tamamlandığını varsaymak yerine doğrulama alınmalıdır. Her entegrasyon sahibi, yeni sürümle birlikte test ortamında veya kontrollü üretim trafiğinde doğrulama yapmalıdır. Bu doğrulama kısa bir onay formu kadar basit olabilir; ancak kritik istemciler için örnek isteklerin ve yanıtların otomatik test edilmesi daha güvenlidir.

Geri bildirim toplarken şu sorulara odaklanılabilir:

• Yeni sözleşmede anlaşılmayan veya eksik kalan alan var mı?
• İstemcinin geçişini engelleyen doğrulama ya da hata davranışı bulunuyor mu?
• Yanıt gecikmesi, veri boyutu veya çağrı sayısında sorun oluştu mu?
• Migration dokümanındaki örnekler gerçek kullanım senaryosunu karşılıyor mu?
• Eski sürümün kapatılması için ek süre veya teknik destek gerekiyor mu?

Geri bildirimler yalnızca e-posta kutusunda birikmemeli, kararlara bağlanmalıdır. Sorumlu ekip her bildirimi teknik hata, dokümantasyon eksikliği, tasarım sorunu veya istemciye özel durum olarak sınıflandırabilir. Ölçülebilir gözlem noktası, açık kalan kritik sorunların sayısı ve doğrulama yapmayan istemcilerin listesidir.

7. Destek sonlandırma tarihini ve koşullarını duyurun

Eski sürümün destek sonlandırma kararı, geçiş metrikleri ve istemci doğrulamaları incelendikten sonra duyurulmalıdır. Duyuruda yalnızca tarih değil, bu tarihten sonra ne olacağı da açıklanmalıdır. Örneğin endpoint tamamen hata mı döndürecek, sınırlı bir hata yanıtı mı verecek, yoksa yalnızca belirli istemciler için erişim mi durdurulacaktır?

Destek sonlandırma tarihi belirlenirken ilgili sözleşme, mevzuat, SLA veya platform politikası varsa bunlar ayrıca kontrol edilmelidir. Bu tür koşullar teknik ekip tarafından varsayılarak belirlenmemeli, ilgili hukuk, satın alma, güvenlik veya operasyon ekipleriyle doğrulanmalıdır.

Duyuruda aşağıdaki bilgilerin bulunması geçiş belirsizliğini azaltır:

• Eski sürümün destek sonlandırma tarihi.
• Bu tarihten önce yapılması gereken istemci değişiklikleri.
• Tarih sonrasında beklenen HTTP durum kodu veya hata biçimi.
• Kritik istemciler için istisna veya ek değerlendirme süreci.
• Son teknik destek tarihi ve iletişim kanalı.
• Geri dönüş veya geçici uzatma kararının hangi koşullarda değerlendirileceği.

Sorumlu ekip, duyurunun tüm entegrasyon sahiplerine ulaştığını doğrulamalıdır. Ölçülebilir gözlem noktaları arasında bildirim teslim durumu, onaylanmamış kritik istemciler ve destek sonlandırma tarihine yaklaşırken v1 trafik oranı bulunur.

8. Eski endpoint’i kontrollü biçimde kapatın ve dokümantasyonu güncelleyin

Kapatma işlemi tek adımlı ve geri döndürülemez bir operasyon olmamalıdır. Önce düşük riskli istemcilerde veya sınırlı trafik diliminde uygulanabilir. Ardından hata oranı, destek talepleri ve kritik iş akışları izlenerek kapsam genişletilebilir.

Eski endpoint kapatıldığında verilen hata yanıtı da anlaşılır olmalıdır. Yanıtta yeni sürümün karşılığı, migration dokümanının adı veya geliştirici portalındaki yönlendirme bulunabilir. Ancak hata gövdesine sürekli değişebilecek ayrıntılar gömülmemeli; bunun yerine güncel dokümantasyon merkezi kullanılmalıdır.

Kapatma sonrasında şu işlemler tamamlanmalıdır:

• Eski route, controller veya servis katmanının kaldırılması.
• Eski sürüme ait otomatik testlerin güncellenmesi ya da kaldırılması.
• Dashboard, alarm ve log filtrelerinin yeni duruma göre düzenlenmesi.
• API referans dokümanında varsayılan sürümün netleştirilmesi.
• Migration dokümanının kapanış durumuyla güncellenmesi.
• İç mimari kayıtlarında eski sürümün yaşam döngüsünün kapatılması.

Geri dönüş planı burada da korunmalıdır. Kapatma sonrası kritik bir istemcinin gözden kaçtığı anlaşılırsa, eski uygulama paketinin veya route’un kısa süreliğine yeniden devreye alınması gerekebilir. Bunun için kapatma öncesinde son çalışan sürüm, konfigürasyon ve veritabanı uyumluluğu kayıt altına alınmalıdır.

Yayıma almadan önce kısa deprecation kontrol listesi

• Eski ve yeni sözleşme arasındaki alan, veri tipi, hata ve durum kodu farkları incelendi mi?
• Etkilenen istemciler ve sorumlu ekipler envanterlendi mi?
• Yeni sözleşme için otomatik entegrasyon testleri hazır mı?
• Gerçekçi örnek istemcilerle v1 ve v2 yanıtları test edildi mi?
• Log, trafik, hata ve sürüm metrikleri için dashboard ve alarm tanımlandı mı?
• Migration dokümanı; yeni karşılık, örnekler, riskler ve iletişim kanalını içeriyor mu?
• Eski sürümün çalışır tutulacağı geçiş koşulları açık mı?
• Destek sonlandırma koşulları ilgili sözleşme, SLA veya politika açısından kontrol edildi mi?
• İstemcilerden doğrulama veya geri bildirim toplama yöntemi belirlendi mi?
• Kapatma sonrası geri dönüş planı, deployment ve konfigürasyon düzeyinde hazır mı?
• Eski endpoint kapatıldığında dokümantasyon, testler, loglar ve alarmlar güncellenecek mi?

Flask ile /v1 ve /v2 API Endpoint’leri Nasıl Gösterilir?

Flask ile API versiyonlamanın temel mantığını göstermek için aynı kullanıcı kaynağını iki farklı route altında sunabiliriz. /v1/users/1 mevcut sözleşmeyi korurken, /v2/users/1 aynı veriyi daha düzenli veya yeniden adlandırılmış bir temsil olarak döndürebilir. Python temelini route tanımı, sözlük yapısı ve JSON yanıt davranışı üzerinden birebir pekiştirmek isteyenler için birebir Python dersleri bu tür küçük API örneklerini adım adım uygulamaya yardımcı olabilir.

from flask import Flask, jsonify

app = Flask(__name__)

@app.get("/v1/users/1")
def user_v1():
    return jsonify({"id": 1, "name": "Ayşe", "email": "[email protected]"})

@app.get("/v2/users/1")
def user_v2():
    return jsonify({"id": 1, "profile": {"name": "Ayşe"},
                    "contact": {"email": "[email protected]"}})

if __name__ == "__main__":
    app.run(debug=True)

Bu uygulama çalıştırıldığında iki endpoint aynı kullanıcıyı farklı sözleşmelerle temsil eder. /v1/users/1 yanıtında alanlar doğrudan üst seviyededir:

{
  "id": 1,
  "name": "Ayşe",
  "email": "[email protected]"
}

/v2/users/1 yanıtında ise kullanıcı adı ve iletişim bilgisi ayrı nesneler altında gruplanmıştır:

{
  "id": 1,
  "profile": {
    "name": "Ayşe"
  },
  "contact": {
    "email": "[email protected]"
  }
}

Bu fark, v1 istemcisinin name alanını okumaya devam ederken v2 istemcisinin profile.name yolunu kullanmasını gerektirir. Eski route’un bir süre daha çalışması, istemci ekiplerine kodlarını kontrollü biçimde güncelleme fırsatı verir. Böylece tek bir anda bütün istemcileri değiştirmek yerine, geçişi istemci bazında planlamak mümkün olur.

Gerçek bir API’de yalnızca route adlarına /v1 ve /v2 eklemek yeterli bir versiyonlama stratejisi değildir. Sözleşme farkları belgelenmeli, istek doğrulama kuralları test edilmeli, örnek istemcilerle entegrasyon sınanmalı, trafik ve hata metrikleri izlenmeli ve eski sürümün kullanımdan kaldırılacağı iletişim planı oluşturulmalıdır. Ayrıca gerçek veriler sabit kodlanmak yerine servis veya veritabanı katmanından alınmalı; yetkilendirme, hata yönetimi ve gözlemlenebilirlik üretim koşullarına göre tasarlanmalıdır.

Sık Sorulan Sorular

Yeni bir alan eklemek için API sürümünü artırmak gerekir mi?

Her yeni alan için sürüm artırmak gerekmez. Mevcut istemcilerin beklediği yanıt yapısını bozmadan, özellikle opsiyonel bir alan eklemek çoğu durumda geriye dönük uyumlu kabul edilebilir. Ancak bazı istemciler beklenmeyen alanları hata olarak işliyorsa veya eklenen alan mevcut davranışı değiştiriyorsa risk oluşabilir. Alanın zorunlu hâle gelmesi, veri tipinin değişmesi, mevcut alanın kaldırılması ya da anlamının değiştirilmesi sürümleme ihtiyacını güçlendirir. Karar verirken teknik değişiklik kadar istemcilerin gerçek davranışı da incelenmelidir.

URL tabanlı API versiyonlama mı, header tabanlı versiyonlama mı daha kolay yönetilir?

URL tabanlı versiyonlama, sürümün endpoint adresinde görünür olması nedeniyle izleme, dokümantasyon, hata ayıklama ve istemci geçişi açısından genellikle daha kolay anlaşılır. Header tabanlı versiyonlama daha temiz bir kaynak URL’si sunabilir; ancak istemcinin doğru header’ı gönderip göndermediğini gözlemlemek ve önbellekleme davranışını doğru yapılandırmak daha fazla dikkat gerektirebilir. Çok sayıda istemciyle çalışan ekipler için görünürlük ve operasyonel sadelik öncelikliyse URL yaklaşımı; merkezi istemci kontrolü ve gelişmiş içerik pazarlığı varsa header veya media type yaklaşımı değerlendirilebilir.

Bir API sürümünü kullanımdan kaldırmadan önce hangi metrikler izlenmelidir?

Öncelikle eski sürümün toplam istek sayısı ve toplam trafik içindeki payı izlenmelidir. Bunun yanında istemci veya API anahtarı bazında kullanım, endpoint başına son çağrı zamanı, HTTP 4xx ve 5xx oranları, gecikme, zaman aşımı, istemci sürümü ve açık destek talepleri incelenmelidir. Düşük trafikli fakat kritik bir iş akışının gözden kaçmaması için yalnızca toplam kullanım oranına bakılmamalıdır. Örneğin eski sürümün kullanım oranı düşse bile kritik istemcilerden biri hâlâ düzenli çağrı yapıyorsa kapatma kararı ertelenebilir.

Breaking change yapmadan API yanıtı nasıl geliştirilebilir?

Yeni bilgileri opsiyonel alanlar olarak eklemek, mevcut alanları korumak ve yeni davranışı ayrı bir endpoint ya da yeni bir medya türüyle sunmak tercih edilebilir. Alan adlarını yeniden adlandırmak yerine bir geçiş süresince eski ve yeni alanları birlikte döndürmek de kullanılabilir; ancak iki alanın aynı anlama geldiği ve hangisinin tercih edildiği belgelenmelidir. Veri tipini değiştirmek, mevcut alanı kaldırmak veya zorunlu yeni istek parametresi eklemek yerine önce uyumluluk katmanı tasarlanmalıdır. Bu yaklaşım istemci güncellemelerini zamana yayarak breaking change riskini azaltır.

API versiyonlama örneğini Python ile nasıl test edebilirim?

Önce v1 ve v2 endpoint’lerine istek göndererek HTTP durum kodlarını ve JSON alanlarını doğrulayabilirsiniz. Ardından v1 yanıtında name alanının, v2 yanıtında ise profile.name alanının bulunduğunu test etmek gerekir. Daha güvenilir bir süreçte her sürüm için başarılı istek, geçersiz kaynak, eksik kimlik doğrulama ve beklenmeyen parametre senaryoları ayrı ayrı yazılmalıdır. Flask uygulamasının test istemcisi veya Python tabanlı bir HTTP test aracı kullanılabilir; önemli olan yalnızca endpoint’in cevap vermesi değil, sözleşmenin beklenen biçimde korunmasıdır.

Başarılı bir API geçişi, yeni endpoint’i yayımlamakla değil; sözleşmeyi belgelemek, istemcileri ölçmek, geri bildirim toplamak ve eski sürümü kontrollü biçimde kapatmakla tamamlanır.