Bir API’de değişiklik ihtiyacı doğduğunda sık duyulan cümle şudur:

Bunu v2’de yaparız.

Sonra /v2 yolu açılır. Bir süre iki versiyon birlikte yaşar. Eski client’lar /v1 kullanmaya devam eder. Kimse onları taşımaz. İki yıl sonra /v3 gelir ve backend üç farklı sözleşmeyi aynı anda desteklemek zorunda kalır.

Versiyonlama gerekli bir araç.

Ama çoğu durumda asıl ihtiyaç versiyonlamak değil, kırmadan değiştirebilmek.

Breaking change nedir?

Bir değişikliğin breaking olup olmadığını belirleyen şey, mevcut bir client’ın hiçbir değişiklik yapmadan çalışmaya devam edip etmediğidir.

Genellikle güvenli olanlar:

  • Response’a yeni ve opsiyonel bir alan eklemek
  • Yeni bir endpoint eklemek
  • Request’e varsayılan değeri olan opsiyonel bir parametre eklemek

Genellikle kıranlar:

  • Bir alanı silmek veya yeniden adlandırmak
  • Bir alanın tipini değiştirmek
  • Opsiyonel bir request alanını zorunlu yapmak
  • Hata kodlarının veya status code’ların anlamını değiştirmek

Bir de gri alan var. Enum’a yeni bir değer eklemek teknik olarak bir ekleme. Ama switch ifadesinde bilinmeyen değeri beklemeyen bir client için breaking change. Mobil uygulamalarda özellikle can yakıcı, çünkü eski versiyonlar yıllarca kullanıcıların telefonlarında kalabiliyor.

Tolerant reader

Geriye uyumluluk sadece API sağlayıcısının sorumluluğu değil.

Client’ların da bilmediği alanları görmezden gelmesi gerekir. Jackson’ın varsayılan ayarlarında bilinmeyen bir alan exception’a yol açabiliyor:

spring.jackson.deserialization.fail-on-unknown-properties=false

Spring Boot bu değeri zaten false olarak ayarlıyor ama Jackson’ı doğrudan kullanan kodda bu ayrıca kontrol edilmeli.

Enum’lar için de bilinmeyen değerler bir UNKNOWN sabitine düşürülebilir. Bu yaklaşıma tolerant reader deniyor. Sağlayıcının API’yi genişletmesine izin verir.

Expand and contract, API versiyonu

Bir alanı yeniden adlandırmak gerekiyorsa, bunu tek adımda yapmak zorunda değiliz.

{
  "name": "Akif",
  "fullName": "Akif Şen"
}

Önce yeni alan eklenir. Eski alan bir süre birlikte döner ve dokümantasyonda deprecated olarak işaretlenir. Client’lar yeni alana geçer. Eski alanın kullanımı ölçülür ve sıfıra yaklaştığında kaldırılır.

Bu, veritabanı migration’larında kullanılan expand and contract yaklaşımının API karşılığı.

Kritik kısım ölçmek. Eski alanın veya endpoint’in hâlâ kim tarafından kullanıldığını bilmeden kaldırmak, tahmine dayalı bir karar olur. Request loglarında client kimliği veya user agent tutmak bu yüzden önemli.

Kaldırma tarihi yaklaşırken Deprecation ve Sunset header’ları ile client’lara makine tarafından okunabilir bir uyarı da verilebilir.

Versiyon gerçekten gerektiğinde

Bazen kırmadan ilerlemek mümkün değildir. Kaynak modeli kökten değişmiştir veya eski davranışı korumanın maliyeti çok yüksektir.

Bu durumda versiyonlama doğru araçtır. URL’de (/v2/orders), header’da veya media type’ta yapılabilir. URL yaklaşımı daha az zarif ama en görünür ve en kolay debug edilebilir olanı. Ben genellikle onu tercih ediyorum.

Ama versiyon açarken iki şeyi baştan planlamak gerekiyor: eski versiyonun ne zaman kapanacağı ve client’ların nasıl taşınacağı. Bu ikisi planlanmadan açılan her yeni versiyon, bakımı süresiz uzayan bir sözleşme demek.

Contract test

API’nin istemeden kırılmasını önlemenin en etkili yolu, sözleşmeyi test etmektir.

OpenAPI şemasını CI’da bir önceki versiyonla karşılaştıran araçlar, silinen alanları veya değişen tipleri merge’den önce yakalayabiliyor. Consumer-driven contract testing ise client’ların gerçekten hangi alanlara bağımlı olduğunu açıkça kaydediyor.

İyi bir API, tasarlandığı ilk gün değil, beşinci kez değiştirildiğinde anlaşılır.

Asıl soru “nasıl versiyonlarız?” değil, “nasıl kimseyi kırmadan değiştiririz?” olmalı.