𝟵 𝗔𝗣𝗜 𝗖𝗵𝗮𝗻𝗴𝗲𝘀 𝗧𝗵𝗮𝘁 𝗕𝗿𝗲𝗮𝗸 𝗬𝗼𝘂𝗿 𝗔𝗽𝗽

Uygulamanızı Bozan 9 API Değişikliği

"Hiçbir şeyi bozmadık. Sadece yanıtı temizledik."

Bu sözler genellikle çökmelere yol açar. Bir mobil uygulama hata verir. Bir iş ortağı entegrasyonu anlamsız veriler döndürür. Başkalarının bağımlı olduğu verinin yapısını değiştirdiniz.

Tehlikeli değişiklikler genellikle bir düzenleme gibi görünür. Kod incelemelerinden ve testlerden geçerler. Kırılma ise göremediğiniz kodlarda gerçekleşir.

İşte güvenli gibi görünen ama aslında öyle olmayan dokuz değişiklik.

• Alan adlarını değiştirmek Tutarlılık adına userId değerini user_id olarak değiştirmek istemcileri bozar. Yeniden adlandırma, aslında bir silme ve bir ekleme işlemidir. Silme kısmı ise kullanıcıları mağdur eder. Güvenli adım: Yeni alanı ekleyin. Eski alanı tutun. Onu kullanımdan kaldırın (deprecate). Çok daha sonra silin.

• Bir alanı isteğe bağlı (optional) hale getirmek Bir alan eskiden oradaydı. Şimdi ise bazen null dönüyor. İstemci kodu, bu alanı işlemeye çalıştığında çöker. Güvenli adım: "Her zaman mevcut olma" durumunu bir söz olarak kabul edin. Eğer bir alan isteğe bağlı hale geliyorsa, yeni bir sürüm kullanın.

• Kullanılmayan alanları kaldırmak Tüketicilerinizin verilerinizi nasıl kullandığını göremezsiniz. "Kullanılmayan" ifadesi sadece "sizin tarafınızdan kullanılmayan" anlamına gelir. Güvenli adım: Herhangi bir şeyi kaldırmadan önce üretim ortamında (production) alan kullanımını ölçün.

• Girdi türlerini daraltmak Bir string değerini enum yapmaya veya bir sayıyı integer yapmaya çalışmak istekleri bozar. Bir girdiyi genişletmek güvenlidir; daraltmak ise bozucu bir değişikliktir. Güvenli adım: Sadece kabul ettiğiniz girdileri esnetin. Sıkılaştırmak yeni bir sürüm gerektirir.

• Varsayılan değerleri değiştirmek Varsayılan bir değeri false yerine true yapmak, hata vermeden davranışı değiştirir. Bu, mantığı sessizce bozar. Güvenli adım: Varsayılan değer değişikliğini bozucu bir değişiklik olarak kabul edin.

• Zorunlu alanlar eklemek tenantId eklemek ve bunu zorunlu kılmak, mevcut tüm istemcileri bozar. 400 hatası alacaklardır. Güvenli adım: Yeni alanlar isteğe bağlı olmalı veya yeni bir sürüm kullanılmalıdır.

• Hata formatlarını değiştirmek 400 hatasını 422 ile değiştirmek veya hata gövdesini (error body) değiştirmek, hata işleme kodunu bozar. Güvenli adım: Hata formatları birer sözleşmedir. Diğer her şey gibi onları da versiyonlayın.

• Enum değerlerini değiştirmek active değerini ACTIVE olarak yeniden adlandırmak istemcileri bozar. Bir değeri kaldırmak, katı mantığa sahip istemcileri bozar. Güvenli adım: Enum değerleri sonsuzdur. Onları dikkatlice ekleyin. Büyük bir sürüm değişikliği yapmadan asla yeniden adlandırmayın veya silmeyin.

• Veri anlamını değiştirmek Bir tarihi Unix saniyesinden ISO-8601 formatına çevirmek veya sayfalama (pagination) yöntemini offset yerine cursor yapmak her şeyi bozar. Bir şema farkı (schema diff) bunları yakalayamayabilir bile. Güvenli adım: Formatları açıkça sabitleyin. Sadece spesifikasyonu değil, gerçek veri yüklerini (payloads) karşılaştırın.

Sadece hislerinize güvenmeyin. Her değişikliği CI sürecinizde üretim sözleşmesiyle (production contract) karşılaştırın. Bir insan yeniden adlandırılmış bir alanı gözden kaçırabilir, ancak bir diff aracı kaçırmaz.

Kaynak: https://dev.to/deepaksatyam/9-api-changes-that-look-backwards-compatible-but-arent-1bk0