API Versioning

API versioning (API sürümleme), mevcut istemcilerin, API'yi geliştirdiğinizde çalışmaya devam etmesi için bir public API'deki değişiklikleri yönetme pratiğidir. Başkalarının uygulamaları, mobil istemcileri ve entegrasyonları sizin yanıt şekillerinize bağlı olduğu için bir alanı öylece yeniden adlandıramaz ya da bir endpoint'i kaldıramazsınız — bu onları sessizce bozar. Sürümleme, kırıcı değişiklikleri yeni bir sürüm (v1, v2) altında göndermenize, eski sürüm ise hizmet vermeye devam ederken, olanak tanır. Yaygın stratejiler URL tabanlı (/v1/orders), header tabanlı (Accept: application/vnd.api+json;version=2) ya da query parametreleridir. Daha geniş disiplin, kırıcı değişiklikleri (bir alanı kaldırmak, bir tipi değiştirmek) geriye dönük uyumlu olanlardan (opsiyonel bir alan eklemek) ayırmak ve sürümü yalnızca ilki için yükseltmektir. Public ya da partner API'si gönderen AI/SaaS ekipleri için sürümleme, net bir kullanımdan kaldırma (deprecation) politikasıyla birlikte, her müşteriyi bozmadan içeride hızlı hareket etmenizi sağlar. Pratik not: yalnızca v1'iniz olsa bile ilk günden sürümleyin ve bir şeyi kaldırmadan çok önce kullanımdan kaldırma takvimlerini duyurun.