API sürümleme: Entegrasyonları bozmadan değişiklik yapmak
· PoolByte Technology
Bir API’ye yeni alan eklemek kolay görünür; fakat başka uygulamalar o yanıtı kendi kurallarıyla okuyordur. Alan adını, türünü veya hata biçimini değiştirmek müşterinin entegrasyonunu bozabilir. API sürümleme, bu değişikliklerin hangi sözleşme içinde sunulacağını ve tüketicilerin nasıl geçeceğini belirler.
Önce sözleşmeyi görünür yapın
Yanıt alanları, türler, boş değerler, tarih biçimi ve hata kodları dokümante edilmelidir. Sözleşme yalnız başarılı örnekten oluşmaz. Geçersiz istek, yetki yokluğu ve bulunamayan kayıt da tüketicinin işleyeceği yanıt biçimleridir. Eksik alan ile açıkça null gönderilen alanın aynı anlama gelip gelmediğini belirtin.
Google API sürümleme rehberi, sürümleri kullanıcıya sunarken tutarlı bir yaklaşım kullanmayı tartışır. URL, başlık veya başka bir sürüm seçimi kullanılabilir; önemli olan uygulamanın desteklediği kuralın açık ve öngörülebilir olmasıdır. Geliştirme ekibinin iç sürüm numarasıyla müşterinin API sözleşmesi aynı olmak zorunda değildir.
Her ekleme gerçekten uyumlu olmayabilir
Yeni bir alan çoğu toleranslı istemcide sorun çıkarmasa da katı şema doğrulayan tüketiciler etkilenebilir. Bir enum’a yeni değer eklemek, yalnız eski değerleri bekleyen uygulamayı bozabilir. Sayı alanını metne çevirmek veya tarih biçimini değiştirmek ise daha belirgin bir uyumluluk sorunudur. Değişikliği yalnız sunucu derleniyor diye güvenli saymayın.
Örneğin bir siparişin durumuna “incelemede” değeri ekleniyor. Eski istemci bu değeri “ödendi” veya “başarısız” gibi yanlış bir duruma çevirmemelidir. Bilinmeyen değerde güvenli davranış, dokümante edilmiş olmalıdır. Test kümesine eski istemci sürümünü de eklemek bu tür sorunları erken gösterir.
Geçiş takvimi teknik teslimin parçasıdır
Yeni sürüm için örnek istekler, değişiklik listesi ve test ortamı sağlayın. Eski sürümün ne kadar süre destekleneceğini açıklayın. Kapanış tarihini değiştirmek gerekiyorsa müşterileri zamanında bilgilendirecek bir süreç belirleyin; yalnız dokümanın altına not eklemek etkin kullanım yapan müşteriye ulaşmayabilir.
Kullanım ölçümlerinde hangi tüketicinin eski sürümde kaldığını takip edin. Kimlik veya istek gövdesindeki kişisel bilgileri gereksiz yere günlüğe yazmadan, sürüm ve entegrasyon kimliği yeterli olabilir. Bir müşterinin yeni sürüme geçtiğini tek bir deneme isteğiyle varsaymayın; gerçek iş akışlarının yeni sözleşmeyle tamamlanmasını doğrulayın.
Otomatik kontroller neyi kapsamalı?
- Önceki örnek yanıtlarla sözleşme karşılaştırması.
- Eksik, boş ve bilinmeyen alan değerleri.
- Sayfalama ve hata yanıtlarının tutarlılığı.
- İki sürümün aynı kullanıcıya aynı yetkiyi uygulaması.
- Sürüm geçişinde veri ve durum eşleştirmeleri.
- Eski sürüm kullanımının izlenmesi ve kapanış provası.
Entegrasyon projelerinde webhook teslimi de benzer bir sözleşme disiplini gerektirir; ancak sürümleme burada API tüketicisinin neyi nasıl okuyacağını belirler. Başarı, yeni sürüm yayımlandığında değil, bağımlı uygulamalar kontrollü biçimde geçebildiğinde ortaya çıkar.