API Versiyonlama: Entegrasyonları Bozmadan Değişiklik Yapmak

Sözleşmeyi yalnızca JSON örneğiyle tarif etmeyin

Alan türleri, zorunluluk, boş değer davranışı, sıralama ve hata yanıtları sözleşmenin parçasıdır. Bir alanın aynı isimle kalıp anlamının değişmesi de kırıcı olabilir. Örneğin “total” önce vergi hariç, sonra vergi dahil toplamı gösterirse istemci kodu hata vermeden yanlış hesap yapabilir.

OpenAPI, API arayüzünü yapılandırılmış biçimde tanımlamak için kullanılan bir spesifikasyondur. [2] Tanım dosyasının bulunması yararlıdır ama iş anlamlarını otomatik çözmez. Alan açıklamaları ve örnekler gerçek davranışla birlikte güncel tutulmalıdır.

Eklenen alanın bile etkisini değerlendirin

Yeni isteğe bağlı alan çoğu esnek istemci için sorun yaratmayabilir. Ancak katı doğrulama kullanan tüketici tanımadığı alanı reddedebilir. Benzer şekilde enum listesine yeni durum eklenmesi, bütün seçenekleri sabit kabul eden kodu bozabilir. Değişikliği yalnızca sunucu bakışından değerlendirmeyin.

Microsoft API tasarım rehberi sürümleme yaklaşımlarını ve istemci bağımlılıklarını ele alır. [1] URL, başlık veya başka bir yöntem seçilebilir; asıl gereklilik hangi sözleşmenin ne zaman geçerli olduğunun açık olmasıdır. Her küçük değişiklikte yeni sürüm açmak da gereksiz bakım yükü oluşturabilir.

Örnek: siparişe yeni bir durum ekleniyor

Varsayımsal API “hazırlanıyor” ve “gönderildi” durumlarına sahipken “kısmen gönderildi” ekleniyor. Eski müşteri uygulaması bu değeri tanımadığında ne gösterecek? Genel bir bilinmeyen durum davranışı yoksa sipariş ekranı kapanabilir veya yanlışlıkla tamamlandı görünebilir.

Bu tablo kırıcı değişikliği belirlemek için başlangıç çerçevesidir. Tüketicilerin gerçek kullanımını bilmeden bütün değişiklikleri güvenli ilan etmeyin.

Tüketici envanteri olmadan kapatma tarihi koymayın

Hangi uygulamanın hangi uç noktayı ve sürümü kullandığını bilmek önemlidir. Erişim günlüklerinde gerekli teknik bağlamı tutarken hassas verileri toplamamaya dikkat edin. Kullanılmayan sürüm ile az ama kritik müşteri kullanan sürüm farklı değerlendirilmelidir.

Geçiş bildiriminde değişiklik nedeni, örnek yeni istek, uyarlama adımları ve test ortamı yer alsın. Eski sürümün ne zaman kapanacağı ve hangi istisnaların ele alınacağı açık olmalıdır. Bu tarihler kullanıcıyla kararlaştırılmış plan olmalı; rehberde evrensel süre önerilmemelidir.

İki sürümün veri anlamını koruyun

Eski ve yeni API aynı veri tabanını kullanıyorsa yeni alanların eski yanıtı nasıl etkilediğini inceleyin. Dönüşüm katmanı gerekli olabilir. Eski istemci güncel kaydı okurken anlamını kaybetmemeli; yeni istemci de geçiş döneminde eksik veriyi yönetebilmelidir.

Yazma işlemlerinde daha dikkatli olun. Eski istemci bir kaydı güncellerken yeni alanları yanlışlıkla silebilir. Kısmi güncelleme, varsayılan değer ve bilinmeyen alan davranışını açık tanımlayın. Aynı kaydı iki sürümden sırayla değiştirerek kabul testi yapın.

Teslimde sözleşme testi ve geri dönüş planı isteyin

Testler yalnızca sunucunun beklediği örnekleri değil, desteklenen istemcilerin gerçek sözleşmelerini kapsasın. Başarılı yanıt, hata, boş liste, büyük veri ve yetkisiz istek örnekleri bulunsun. Dokümantasyon değişikliğiyle kod değişikliğinin aynı sürümde yayımlandığı kontrol edilsin.

Yeni sürüm sorun çıkarırsa yönlendirme geri alınabiliyor mu? Veri dönüşümü geri dönüşü engelliyorsa uygulama sürümünü eskiye almak tek başına yeterli değildir. Yayın kararı API ve veri geçişi birlikte değerlendirilerek verilmelidir.

Sık sorulan sorular

### Her değişiklikte v2 açmalı mıyım? Hayır. Önce tüketici sözleşmesini bozup bozmadığını değerlendirin. Sürüm sayısını artırmak uyumluluk analizinin yerine geçmez.

Dokümantasyon güncelse test gereksiz mi?

Hayır. Doküman niyeti, test gerçek davranışı gösterir. Desteklenen istemcilerle hata ve sınır durumları doğrulanmalıdır.