Bir API canlıya çıktıktan sonra, onu kullanan istemcileri kırmadan değişiklik yapmak giderek zorlaşıyor. Versiyonlama stratejisini baştan doğru kurmak, bu zorluğu büyük ölçüde azaltıyor.
URL Tabanlı Versiyonlama
En yaygın ve benim de en çok tercih ettiğim yaklaşım, versiyonu URL'ye koymak: /api/v1/orders, /api/v2/orders. Bu, hem istemciler için açık ve anlaşılır hem de farklı versiyonların loglarda ve dokümantasyonda kolayca ayırt edilmesini sağlıyor.
Header Tabanlı Versiyonlama
Bazı projelerde versiyon bilgisini bir HTTP header'ında (Api-Version: 2.0) taşımayı tercih ediyorum; bu, URL'yi temiz tutuyor ama istemci tarafında biraz daha az görünür oluyor. Hangi yaklaşımı seçeceğim, projenin istemci kitlesine (iç ekip mi, dış geliştiriciler mi) bağlı.
Kırıcı Olmayan Değişiklikleri Versiyonsuz Yapmak
Yeni bir opsiyonel alan eklemek gibi geriye dönük uyumlu değişiklikler için yeni versiyon açmıyorum; sadece gerçekten kırıcı değişikliklerde (bir alanın kaldırılması, tipin değişmesi) yeni versiyon oluşturuyorum. Her küçük değişiklikte versiyon artırmak, istemcileri gereksiz yere yeni versiyona geçmeye zorluyor.
Eski Versiyonları Ne Zaman Kaldırmalı?
Bir versiyonu kaldırmadan önce, kullanım metriklerine bakıp hâlâ trafik alıp almadığını kontrol ediyorum. İstemcilere önceden (genelde birkaç ay) bildirim yaparak, ani bir kesintiyle karşılaşmalarını engelliyorum.
Sonuç
API versiyonlama, "en başında bir kez kurup unutulacak" bir konfigürasyon değil, API'nin yaşam döngüsü boyunca sürekli yönetilmesi gereken bir süreç. Baştan net bir strateji belirlemek, ileride yaşanacak sürtünmeyi büyük ölçüde azaltıyor.