API sözleşmesini sürümlemek: kırıcı değişiklikleri yönetmek ve test etmek

Bir API'nin ilk sürümünde alan eklemek, endpoint adını değiştirmek veya hata gövdesini düzenlemek küçük bir refaktör gibi görünebilir. Ancak API, yayımlandığı anda başka bir kod tabanının derleme ve çalışma zamanı bağımlılığı hâline gelir. Web istemcisi, mobil uygulama, tarayıcı eklentisi, arka plan worker'ı veya üçüncü taraf entegrasyon; aynı davranışa sessizce güveniyor olabilir.

Bu yüzden API sözleşmesi yalnızca OpenAPI dosyası ya da DTO sınıfı değildir. URL, HTTP metodu, istek ve yanıt alanları, varsayılanlar, sıralama, sayfalama, hata biçimi, yetki davranışı ve zaman aşımı beklentileri sözleşmenin parçasıdır. Sağlam sürümleme, her değişikliği yeni bir sürüme koymak anlamına gelmez; hangi değişikliğin istemciyi kırdığını, hangisinin güvenle genişletilebildiğini ve bunları nasıl kanıtlayacağınızı bilmektir.

Önce tüketiciyi ve kullanım biçimini görün

Bir endpoint'in kimin tarafından kullanıldığını bilmeden uyumluluk kararı verilemez. Sadece aynı depodaki frontend'i düşünmek yeterli değildir. Eski mobil sürümler, otomasyon betikleri veya bağımsız servisler zamanla geride kalabilir.

Envanter için şu sorular faydalıdır:

• Bu endpoint'i veya mesajı hangi uygulamalar kullanıyor?
• İstemciler ne sıklıkla güncelleniyor, eski sürümler ne kadar yaşıyor?
• Alan gerçekten kullanılıyor mu, yoksa yalnızca dokümanda mı var?
• Bir tüketicinin güncellenmesi mümkün değilse geçiş planı nedir?

Erişim logları, API gateway metrikleri ve kod araması bu envantere yardımcı olabilir. Ancak bir alanın az kullanılmasının güvenle silinebileceği anlamına gelmediğini unutmayın; düşük hacimli bir entegrasyon iş açısından kritik olabilir. Sürümleme kararı, teknik gözlem ile ürün sahipliğini birlikte gerektirir.

Eklentiye açık tasarım varsayılan olsun

Geriye uyumlu değişikliklerin en güvenli türü, mevcut anlamı değiştirmeden isteğe bağlı bilgi eklemektir. Yanıta yeni alan eklemek, istemci bilinmeyen alanları görmezden gelecek şekilde yazıldıysa çoğu zaman güvenlidir. Benzer biçimde yeni bir endpoint eklemek veya yeni bir hata kodu sınıfını ayrıştırılabilir bir gövdeyle sunmak mevcut çağrıları bozmaz.

Yine de “alan eklemek her zaman güvenlidir” kuralı yoktur. Katı JSON şeması kullanan istemciler, bilinmeyen alanı hata sayabilir. Özellikle enum değerlerine yeni seçenek eklemek dikkat ister: status alanına archived eklemek, istemcinin yalnızca active ve inactive durumlarını bildiği varsayımını bozabilir. Tüketicilerin bilinmeyen değerleri güvenli biçimde ele alması, sözleşmenin açık bir parçası olmalıdır.

İstek gövdesinde yeni alan eklerken sunucunun varsayılan davranışı net olmalıdır. “Alan yoksa ne olur?” sorusunun cevabı sürümler arasında değişmemelidir. Yeni alan zorunlu ise bu genellikle kırıcı bir değişikliktir; geçici varsayılan, iki aşamalı geçiş veya yeni endpoint daha uygun olabilir.

Kırıcı değişikliği erken tanıyın

Aşağıdaki değişiklikler çoğu istemci için kırıcı kabul edilmelidir:

• Endpoint veya HTTP metodunu değiştirmek,
• Zorunlu bir istek alanı eklemek,
• Yanıttaki alanı kaldırmak, yeniden adlandırmak ya da türünü değiştirmek,
• Varsayılan sıralamayı veya sayfalama anlamını değiştirmek,
• Başarı yanıtını farklı HTTP durum koduna taşımak,
• Yetki veya hata davranışını daha dar ya da daha farklı hâle getirmek.

Bazen değişiklik teknik olarak görünmez, fakat iş anlamını değiştirir. Para biriminde tamsayıdan ondalığa geçmek, tarih alanını yerel saatten UTC'ye çevirmek ya da boş diziyi null yapmak, şema aynı kalsa bile tüketiciyi etkileyebilir. Sözleşme incelemesinde alanın türü kadar birimi, zaman dilimi, boşluk anlamı ve sıralama garantisi de sorulmalıdır.

Kullanım dışı bırakma bir süreçtir

Eski alan veya endpoint'i silmek yerine önce kullanım dışı olarak işaretlemek gerekir. Dokümantasyonda yerine geçecek seçenek, geçiş örneği ve hedef tarih görünmelidir. Uygunsa yanıta bir Deprecation veya benzeri uyarı bilgisi eklemek, entegrasyon sahiplerini harekete geçirebilir.

Süreç yalnızca duyurudan ibaret değildir. Kullanım metrikleri eski yolun gerçekten terk edilip edilmediğini göstermelidir. Sabit bir takvim tarihi yerine, tüketici geçişi ve risk değerlendirmesiyle karar vermek daha güvenlidir. Yüksek riskli istemciler için iki sözleşmeyi bir süre paralel yaşatmak, ani kesintiden daha düşük maliyetli olabilir.

Yeni bir ana sürüm gerektiğinde URL'de /v2 kullanmak, header tabanlı sürümleme veya medya türü sürümleme gibi seçenekler vardır. Tek bir doğru mekanizma yoktur; önemli olan seçimi tutarlı uygulamak ve istemcinin hangi sürümle konuştuğunu teşhis edebilmektir.

Sözleşmeyi test edilebilir bir artefakt yapın

Doküman ile çalışan uygulama farklılaştığında, doküman hızla güvenini kaybeder. Sözleşmeyi kaynak kontrolünde tutulan bir artefakt olarak üretmek ve değişiklikte diff incelemek ilk savunmadır. Açık bir şema, hangi alanın kaldırıldığını veya zorunlu hâle geldiğini görünür kılar.

Sağlayıcı tarafında sözleşme testleri, gerçek endpoint'in şemaya ve örnek davranışlara uyduğunu doğrular. Tüketici tarafında ise kritik istemciler kendi beklentilerini test olarak yayımlayabilir. Böylece sağlayıcı, bir alanı değiştirmeden önce hangi tüketicinin etkilenebileceğini CI aşamasında görebilir.

Bu testler yalnızca başarılı yanıtları kapsamaz. Yetkisiz erişim, doğrulama hatası, sayfalama sınırı, boş sonuç, oran sınırlaması ve tekrar deneme davranışı da anlaşmanın parçasıdır. Bir API'nin güvenilirliği, mutlu yol kadar hata anındaki tutarlılığından gelir.

Mesaj sözleşmelerini unutmayın

Kuyruk üzerinden yayımlanan olaylar da API'dir. Bir OrderCreated olayındaki alanı değiştirmek, HTTP endpoint değiştirmekle aynı uyumluluk sorumluluğunu taşır. Olayın şema sürümü, üreticisi, oluşma zamanı ve idempotency bilgisi açık olmalıdır.

Tüketiciler bilinmeyen alanları görmezden gelmeli, olayları sırasız veya tekrar gelmiş kabul ederek tasarlanmalıdır. Yeni olay tipi eklemek çoğu zaman mevcut olayı aşırı yüklemekten daha güvenlidir. Geçmiş olayları yeniden oynatma ihtimali varsa şema evrimi ve migration stratejisi baştan düşünülmelidir.

İyi sürümleme, değişikliği yavaşlatmaz

Sözleşme disiplini bürokrasi gibi görünebilir; aslında değişiklik maliyetini görünür kılar. İstemcinin ne beklediğini, bir değişikliğin neyi bozacağını ve geçişin nasıl izleneceğini bilen ekipler daha hızlı ve daha sakin hareket eder.

Pratik başlangıç basittir: kritik endpoint'ler için kaynak kontrollü şema, uyumluluk diff'i, birkaç sözleşme testi ve açık kullanım dışı bırakma notu. Bunlar yerleştiğinde API, bir servisin iç ayrıntısı olmaktan çıkar; farklı ekiplerin güvenle üzerine inşa edebileceği uzun ömürlü bir ürün yüzeyi olur.