API Versiyonlama: Mevcut Kullanıcıları Bozmadan Geliştirmek

Mobil uygulamanızın yeni sürümü için sunucudaki bir alanın adını değiştirdiniz ve ertesi sabah, telefonunu güncellememiş müşterilerden “uygulama açılmıyor” mesajları gelmeye başladı. Bu tablo, api versiyonlama yapılmadan geliştirilen sistemlerde sık görülür. API versiyonlama, servisinizi geliştirmeye devam ederken onu kullanan eski uygulamaların, iş ortaklarının ve entegrasyonların çalışmaya devam etmesini sağlayan bir sözleşme yönetimidir. Bu yazıda neyin sürüm değişikliği gerektirdiğini, hangi yöntemlerin kullanıldığını ve geçişin nasıl planlandığını anlatıyorum.

API versiyonlama neden gereklidir?

Bir API, sunucunuz ile onu kullanan istemciler arasındaki yazılı olmayan bir sözleşmedir. İstemci belirli bir adrese istek atar, belirli alan adlarıyla belirli biçimde veri bekler. Bu sözleşmenin temelini merak ediyorsanız REST API’nin ne olduğunu anlatan yazıya göz atabilirsiniz.

Web sitesinde değişiklik yaptığınızda tüm ziyaretçiler anında yeni sürümü görür. Mobil uygulamada ve üçüncü taraf entegrasyonlarda durum farklıdır: kullanıcı güncellemeyi haftalarca yapmayabilir, iş ortağınızın yazılımcısı kendi kodunu aylarca değiştirmeyebilir. Sunucu tarafında sözleşmeyi bozduğunuz anda bu istemciler hata vermeye başlar. Versiyonlama, eski istemcilere eski sözleşmeyi sunarken yenilere yeni özellikler açmanızı sağlar.

Hangi değişiklik yeni sürüm gerektirir?

Her değişiklik yeni bir sürüm demek değildir. Kritik ayrım, değişikliğin geriye dönük uyumlu olup olmadığıdır. Mevcut istemcinin hiçbir şey yapmadan çalışmaya devam edebildiği değişiklikler aynı sürümde yapılabilir.

Değişiklik	Geriye uyumlu mu?	Yeni sürüm gerekir mi?
Yanıta yeni bir alan eklemek	Genellikle evet	Hayır
Yeni bir uç nokta (endpoint) eklemek	Evet	Hayır
İsteğe zorunlu olmayan parametre eklemek	Evet	Hayır
Bir alanın adını değiştirmek veya silmek	Hayır	Evet
Alanın veri tipini değiştirmek (sayıdan metne)	Hayır	Evet
Yeni zorunlu parametre eklemek	Hayır	Evet
Hata kodlarının anlamını değiştirmek	Hayır	Evet

Burada bir uyarı: “yeni alan eklemek” genellikle güvenlidir, ama istemci yanıtı katı bir şemaya göre doğruluyorsa sorun çıkarabilir. Bu yüzden istemcilere baştan “tanımadığın alanları yok say” kuralını iletmek iyi bir alışkanlıktır.

API versiyonlama yöntemleri

Sürümü istemciye bildirmenin birkaç yaygın yolu vardır. Hiçbiri tek doğru değildir; seçim projenin yapısına ve kimlerin API’yi kullandığına bağlıdır.

URL içinde sürüm

En yaygın ve en kolay anlaşılan yöntemdir: /api/v1/siparisler ve /api/v2/siparisler gibi. Tarayıcıda, kayıtlarda ve dokümantasyonda hangi sürümün kullanıldığı açıkça görünür. Önbellekleme ve yönlendirme kuralları da basit kalır. Dezavantajı, aynı kaynağın birden fazla adresi olmasıdır; çoğu işletme projesinde bu kabul edilebilir bir bedeldir.

İstek başlığında sürüm

Adres sabit kalır, istemci sürümü bir HTTP başlığıyla bildirir. Daha “temiz” adresler sağlar ama testi ve hata ayıklamayı biraz zorlaştırır; başlığı unutan istemcinin hangi sürüme düşeceği net tanımlanmalıdır.

Sorgu parametresinde sürüm

?version=2 gibi bir parametreyle sürüm seçilir. Uygulaması kolaydır, fakat parametre unutulduğunda varsayılan davranış belirsizleşebilir ve önbellek katmanlarında dikkat gerektirir.

Küçük ve orta ölçekli projelerde genellikle URL içinde ana sürüm numarası kullanmayı, küçük ve uyumlu değişiklikleri ise aynı sürüm içinde yapmayı öneririm. Böylece numara yalnızca gerçekten kırıcı bir değişiklikte artar.

Sürümler arası geçişi planlamak

Yeni sürümü yayınlamak işin yarısıdır. Asıl zorluk, eski sürümü kullananları yeniye taşımak ve sonunda eski sürümü kapatmaktır. Sağlıklı bir geçiş genellikle şu adımları izler:

1. Yeni sürümü paralel yayınlayın: v1 çalışmaya devam ederken v2 açılır. İkisi aynı veritabanını kullanabilir; fark çoğu zaman yalnızca yanıtın biçimindedir.
2. Kullanımı ölçün: Sunucu kayıtlarından hangi istemcinin hangi sürümü çağırdığını izleyin. Kimin geride kaldığını bilmeden kapatma tarihi belirlemek risklidir.
3. Kullanımdan kaldırma duyurusu yapın: Dokümantasyonda, iş ortaklarına e-postayla ve mümkünse yanıt başlıklarında eski sürümün ne zaman kapanacağını bildirin.
4. Mobil uygulamada zorunlu güncelleme kurgulayın: Uygulama açılışta desteklenen en düşük sürümü sorgular; çok eskiyse kullanıcıyı mağazaya yönlendirir.
5. Eski sürümü kapatın: Kullanım sıfıra yakınsadığında v1 kaldırılır ve bakım yükü azalır.

Bu süreçte iyi tutulmuş bir dokümantasyon büyük fark yaratır. Hangi alanın hangi sürümde değiştiğini anlatan bir değişiklik günlüğünün nasıl hazırlanacağını API dokümantasyonu yazısında ayrıca ele aldım.

Sık yapılan hatalar

• Hiç sürüm numarası koymamak: İlk günden v1 ile başlamak neredeyse hiçbir maliyet getirmez, ama sonradan eklemek tüm istemcileri etkiler.
• Her küçük değişiklikte sürüm artırmak: Beş paralel sürümü ayakta tutmak bakım kâbusuna dönüşür.
• Eski sürümü sessizce kapatmak: Duyurusuz kapatma, iş ortağı ilişkilerine zarar verir.
• Kod tekrarını büyütmek: Her sürüm için iş mantığını kopyalamak yerine, ortak iş mantığını tek yerde tutup yalnızca giriş-çıkış katmanını sürüme göre ayırmak daha sürdürülebilirdir.
• Mobil uygulamayı hesaba katmamak: Mobil uygulama bakımı planında eski sürümlerin ne kadar süre destekleneceği baştan yazılmalıdır.

Bu işi nasıl birlikte yaparız?

Mevcut bir API’niz varsa ve değişiklik yapmaktan çekiniyorsanız ya da yeni bir servisi baştan doğru kurmak istiyorsanız süreci genellikle şöyle yürütüyorum:

1. Mevcut durumu inceleme: API’yi kimlerin kullandığını, hangi uygulama sürümlerinin sahada olduğunu ve planlanan değişiklikleri birlikte listeliyoruz.
2. Uyumluluk analizi ve teklif: Hangi değişikliklerin aynı sürümde yapılabileceğini, hangilerinin yeni sürüm gerektirdiğini çıkarıp kapsamı ve takvimi netleştiriyorum.
3. Geliştirme ve paralel test: Yeni sürümü eskisiyle yan yana çalıştırıp hem eski hem yeni istemcilerle test ediyorum.
4. Geçiş ve destek: Kullanım ölçümü, duyuru metinleri ve eski sürümün kapatılması aşamasında yanınızda oluyorum.

Projenizi konuşmak için iletişim sayfasından kısa bir not bırakmanız yeterli.

Sık sorulan sorular

Küçük bir proje için de API versiyonlama gerekir mi?

API’yi yalnızca kendi web siteniz kullanıyorsa ve aynı anda güncelleniyorsa zorunlu değildir. Ancak mobil uygulama veya dış entegrasyon ihtimali varsa ilk günden v1 ile başlamak ileride büyük kolaylık sağlar.

Eski sürümü ne kadar süre açık tutmalıyım?

Sabit bir süre yoktur. Belirleyici olan, eski sürümü kullanan istemci sayısı ve iş ortaklarınızın güncelleme hızıdır. Kayıtlardan kullanımı izleyip makul bir duyuru süresi tanımak en sağlıklı yoldur.

Sürüm numarası 1.2.3 gibi mi olmalı?

API adreslerinde genellikle yalnızca ana sürüm (v1, v2) kullanılır. Küçük ve uyumlu değişiklikler dokümantasyondaki değişiklik günlüğünde ayrıntılı numaralarla izlenebilir.

Versiyonlama performansı etkiler mi?

Doğru kurgulandığında belirgin bir etkisi olmaz. Paralel sürümler aynı iş mantığını ve veritabanını paylaşır; fark çoğunlukla yanıtın biçimlendirilmesindedir.

Sonuç

API versiyonlama, ürününüzü geliştirirken mevcut kullanıcılarınızı korumanın en düzenli yoludur: hangi değişikliğin kırıcı olduğunu bilmek, sürümü açıkça işaretlemek ve geçişi ölçerek yönetmek yeterlidir. API’nizin yol haritasını birlikte çizmek isterseniz bana ulaşabilirsiniz.