Bir API'yi ilk yayına aldığınızda sürümleme sorusu çoğu zaman "sonra bakarız" listesine düşer. Sonra mobil uygulamanın eski sürümü mağazada, yeni sürümü incelemede, backend ise alan adını değiştirmek zorunda kalır. Sürümleme kararı kod yazarken değil, ilk istemci canlıya çıktığında başlar.
URL'de sürüm: görünür ve basit
En yaygın yöntem sürümü yola koymak: /api/v1/orders. Avantajı açık: tarayıcıdan, curl ile, günlük kayıtlarında, hata raporlarında hangi sürümün çağrıldığı ilk bakışta görülür. Laravel'de de karşılığı kolay; Route::prefix('v1') ile bir rota grubu açar, denetleyicileri App\Http\Controllers\Api\V1 altında tutarsınız.
Dezavantajı, sürümün kaynağın kimliğinin bir parçası gibi davranması. /v1/orders/42 ile /v2/orders/42 aynı sipariş, ama iki ayrı adres. Önbellek, yönlendirme ve dokümantasyon tarafında bu ikilik küçük ama sürekli bir yük getirir.
Başlıkta sürüm: temiz adres, gizli maliyet
İkinci yaklaşım adresi sabit tutup sürümü başlıkta taşımak: Accept: application/vnd.firma.v2+json ya da özel bir X-API-Version başlığı. Kaynağın adresi değişmez, içerik pazarlığı HTTP'nin kendi mekanizmasıyla yapılır. Teoride daha zarif.
Sahada gördüğümüz bedeli şu: başlık görünmez. Bir müşteri "siparişler gelmiyor" dediğinde adres çubuğundan bir şey anlayamazsınız. Ara katmandaki bir proxy veya CDN başlığı yok sayarsa yanlış sürüm önbelleğe girer. Önbellek kullanıyorsanız yanıtta Vary: Accept göndermeyi unutmamak gerekir.
Hiçbiri: sürüm çıkarmadan evrilmek
Üçüncü yol, sürüm numarasını mümkün olduğunca ertelemek. Kural basit: mevcut alanı silmezsiniz, türünü değiştirmezsiniz, yalnızca yeni alan eklersiniz. İstemciler bilmedikleri alanı yok sayacak şekilde yazılırsa ekleme işlemleri kimseyi kırmaz. Bunun için ortak bir sözleşme gerekir:
- Yeni alanlar isteğe bağlıdır, varsayılan değeri eski davranışı korur.
- Bir alan kaldırılacaksa önce belgelenir, sonra yanıtta uyarı başlığıyla duyurulur, en son silinir.
- İstemci tarafı JSON ayrıştırması bilinmeyen alanlarda hata vermez; Dart'ta
fromJsoniçinde yalnızca ihtiyaç duyulan anahtarlar okunur. - Enum benzeri değerlerde istemci, tanımadığı değeri güvenli bir varsayılana düşürür.
Mobil istemcilerde asıl kısıt: eski sürümler ölmez
Web arayüzünü istediğiniz an güncelleyebilirsiniz; mobil uygulamayı güncelleyemezsiniz. Kullanıcıların bir kısmı aylarca eski sürümde kalır. Bu yüzden mobil projelerde sürümleme kararını tek başına yola veya başlığa bırakmıyoruz. Uygulama, her istekte kendi sürüm numarasını ayrı bir başlıkta gönderir, sunucu bunu günlüğe yazar ve belirli bir eşiğin altındaki istemciye "güncelleme gerekli" yanıtı döndürebilir. Böylece hangi eski sürümün hâlâ kullanıldığını veriyle görür, desteği ne zaman keseceğinize tahminle değil kayıtla karar verirsiniz.
Bizim tercihimiz
Çoğu projede ana sürümü URL'de tutuyor, küçük değişiklikleri ise sürüm çıkarmadan, yalnızca ekleyerek yönetiyoruz. Yeni ana sürüm ancak sözleşmeyi gerçekten bozan bir değişiklik kaçınılmaz olduğunda açılıyor; örneğin bir kaynağın modeli baştan tasarlandığında. Eski sürüm için bir kapanış tarihi belirleyip bunu dokümantasyona ve yanıt başlıklarına yazıyoruz. İki sürümü sonsuza kadar yaşatmak, kod tabanını sessizce ikiye katlamak demek.
Şunu da ekleyelim: hangi yöntemi seçerseniz seçin, sürümler arasındaki ortak iş mantığını denetleyicide değil servis katmanında tutun. Denetleyiciler yalnızca istek ve yanıt biçimini dönüştürürse v1 ile v2 aynı servisi çağırır ve düzeltilen bir hata iki sürümde birden düzelir.
Kırıcı değişikliği nasıl tanırsınız? Sürüm açıp açmamaya karar verirken şu soruyu sorun: eski bir istemci, hiçbir değişiklik yapmadan yeni yanıtı doğru işleyebilir mi? Cevap hayırsa değişiklik kırıcıdır. Alan adının değişmesi, bir sayının metne dönmesi, bir listenin nesneye dönüşmesi, doğrulama kurallarının sıkılaşması bu gruba girer. Sözleşme testleri (örneğin Laravel'de örnek yanıtların şemaya uyup uymadığını denetleyen testler) bu tür kazaları birleştirme aşamasında yakalamanın en ucuz yoludur.
API'niz için sürümleme stratejisini baştan kurmak ya da canlıdaki bir sistemi istemcileri kırmadan evriltmek isterseniz iletişim sayfamızdan bize ulaşın. 2010'dan bu yana 500'ün üzerinde projede gördüğümüz tablo net: sürümleme kararı ne kadar erken verilirse, sonraki taşıma o kadar ucuz oluyor.