API evrimi denince birçok ekip doğrudan yeni sürüm açmayı düşünüyor. Bazı durumlarda bu gerekli, ancak çoğu durumda kırılma riskini yalnızca erteliyor. Çünkü esas mesele endpoint adı değil sözleşme davranışı.
Bizim ilk adımımız contract archaeology: hangi alanlar gerçekten kullanılıyor, hangi hata kodu istemcide özel akış tetikliyor, hangi endpoint dokümanda var ama trafikte yok? Bu görünmeden yapılan sadeleştirme, beklenmeyen üretim kırıkları doğuruyor.
Değişiklikleri üç kırılma türüne ayırıyoruz. Yapısal kırılma alan tipleri ve zorunluluk ilişkileriyle ilgilidir. Davranışsal kırılma timeout, sıralama ve idempotency beklentilerinde ortaya çıkar. Semantik kırılma ise response aynı görünse de iş anlamı değiştiğinde oluşur.
Deprecation sürecini tek bir tarih ilanı olarak değil operasyonel plan olarak yönetiyoruz. Trafik bazlı etki listesi, tüketici migration panosu ve geri alınabilir kaldırma planı olmadan deprecation güvenli değildir.
Riskli geçişlerde dual-write dönemini zorunlu tutuyoruz. Eski ve yeni model birlikte beslenirken gölge yanıt karşılaştırmasıyla anlam kaymasını erken yakalıyoruz. Kısa vadede karmaşık görünse de büyük taşınmalarda en ucuz sigorta bu yöntem oluyor.
API değişikliği teknik karar gibi görünse de etkisi ürün tarafında hissedilir: eksik bildirim, hatalı fiyat, sessiz veri tutarsızlığı. Bu nedenle değişiklik review’u yalnız backend ekibiyle değil tüketici ekiplerle birlikte yapılmalı.
Uzun ömürlü API başarısı temiz endpoint sayısıyla ölçülmez. Başarı, sözleşme değişimini ölçülebilir, iletişimi net ve gerektiğinde geri alınabilir bir işletim pratiğine dönüştürebilmektir.
