API versiyonlama, sunucu tarafındaki değişikliklerin istemci uygulamalarını bozmadan yayınlanmasını sağlayan kritik bir stratejidir. REST API geliştirirken, zamanla endpoint'lerde, veri yapılarında veya iş mantığında yapılan güncellemeler geriye dönük uyumluluğu tehdit edebilir. Bu nedenle, her API tasarımcısının erken aşamada bir versiyonlama planı oluşturması gerekir. En yaygın üç yöntem URI versiyonlama, header versiyonlama ve query parametreleriyle versiyonlamadır. Hangi yöntemi seçeceğiniz, API'nizin kullanım senaryosuna ve hedef kitlenize bağlıdır.
URI Versiyonlama: En Yaygın ve Basit Yaklaşım
URI'ye versiyon numarası eklemek, en bilindik yöntemdir. Örneğin, /v1/users ve /v2/users şeklinde iki farklı endpoint oluşturursunuz. Bu yöntemin en büyük avantajı, hem geliştiriciler hem de test araçları için son derece açık ve keşfedilebilir olmasıdır. URL'yi gören herkes hangi API sürümünü kullandığını anında anlar.
Ancak bu yaklaşımın dezavantajı, zamanla çok sayıda versiyon birikmesi ve bakım yükünün artmasıdır. Her yeni sürüm, istemciyi yeni bir URL'ye yönlendirir, bu da istemci kodunda değişiklik gerektirir. Özellikle mobil uygulamalarda güncelleme döngüleri uzun olduğu için eski sürümleri desteklemek zorunda kalabilirsiniz. Ayrıca URI versiyonlama, RESTful prensiplerine tam olarak uymaz; çünkü URI'nin kaynağın kimliğini temsil etmesi beklenir, versiyon değil.
Header Versiyonlama: RESTful Ruhuna Daha Uygun
Bu yöntemde versiyon bilgisi HTTP header'ı taşınır. Özel bir header (örneğin Accept-Version: v2) veya Content Negotiation kullanarak Accept header'ına medya türü ekleyebilirsiniz (örneğin Accept: application/vnd.myapi.v2+json). Bu sayede URI temiz kalır ve kaynak odaklı tasarım korunur.
Header versiyonlama, istemci ve sunucu arasında anlaşma sağlamak için esneklik sunar. Örneğin, bir istemci belirli bir versiyonu talep edebilir, sunucu ise desteklenen en yüksek sürüme yönlendirme yapabilir. Ancak bu yöntemin dezavantajı, keşfedilebilirliğin düşük olmasıdır: URL'yi tarayıcıda açmak veya cURL ile test etmek her zaman doğru header'ı eklemenizi gerektirir. Ayrıca bazı ara katmanlar (proxy, CDN) özel header'ları düzgün işlemeyebilir.
Query Parametreleriyle Versiyonlama: Basitlik Uğruna Güvenlikten Ödün
Versiyon bilgisini query string'e eklemek, örneğin /users?version=2, en kolay uygulanabilir yöntemdir. Özellikle hızlı prototipleme veya eski API'leri genişletirken tercih edilir. Ancak bu yöntem, URL'lerin önbelleğe alınması ve güvenlik açısından sorun yaratabilir. Örneğin, önbellek aynı URI'yi farklı versiyonlar için aynıymış gibi algılayabilir. Ayrıca API anahtarları veya token'lar gibi hassas bilgilerin query string'de taşınması güvenlik riski oluşturur. Bu nedenle, üretim ortamlarında önerilmez.
“API versiyonlama yöntemi seçerken sadece teknik kolaylık değil, aynı zamanda istemcilerin güncellenme sıklığı, geriye dönük uyumluluk gereksinimleri ve bakım maliyeti de dikkate alınmalıdır. En iyi strateji, başlangıçta basit bir yöntem seçip ihtiyaç arttıkça daha sofistike bir yapıya geçmektir.”
Karşılaştırmalı Tablo
| Yöntem | Keşfedilebilirlik | RESTful Uyum | Önbellek Dostu | Bakım Kolaylığı | Kullanım Alanı |
|---|---|---|---|---|---|
| URI | Yüksek | Düşük | Yüksek | Orta | Genel amaçlı, halka açık API'ler |
| Header | Düşük | Yüksek | Orta | Yüksek | İç servisler, uzun ömürlü istemciler |
| Query Param | Orta | Orta | Düşük | Düşük | Hızlı prototipler, geçici çözümler |
Versiyonlama Stratejisinde Dikkat Edilmesi Gerekenler
Geriye Dönük Uyumluluk
Yeni bir sürüm yayınladığınızda, eski sürümleri hemen kaldırmayın. İstemcilerin güncellenmesi zaman alır. En az bir geçiş süresi tanıyın ve eski sürümler için sayfalama ve hata yönetimi gibi özellikleri koruyun.
Deprecation Politikası
Sürümlerin ne zaman kullanımdan kaldırılacağını net bir takvimle duyurun. Deprecation header'ı kullanarak istemcileri uyarabilirsiniz. Örneğin, Deprecation: true ve Sunset: Sat, 31 Dec 2026 23:59:59 GMT. Ayrıca, eski sürümleri kullanan istemcilere uyarı mesajları döndürmek iyi bir alışkanlıktır.
Hız Sınırlandırma ve Güvenlik
Eski sürümlerin kötüye kullanımını önlemek için hız sınırlandırma uygularken sürüm bazlı kurallar koyabilirsiniz. Ayrıca, eski sürümlerde güvenlik açıkları varsa, bunları yamalamak veya kullanımdan kaldırmak gerekir. JWT kimlik doğrulama gibi modern standartları eski sürümlerde de desteklemek, güvenlik seviyesini yüksek tutar.
Sık Yapılan Hatalar
- Versiyonlamayı erteleme: Projeye sonradan versiyon eklemek çok zordur. İlk yayında bile bir versiyon numarası (örneğin /v1) kullanın.
- Çok sık versiyon çıkarma: Her küçük değişiklik için yeni sürüm oluşturmak yerine, geriye dönük uyumlu değişiklikleri mevcut sürümde yapın. Büyük kırıcı değişiklikler için sürüm artırın.
- Eski sürümleri sonsuza kadar destekleme: Belirli bir planla eski sürümleri kullanımdan kaldırın. Aksi takdirde bakım yükü katlanarak büyür.
- Dökümantasyonu ihmal etme: Her sürüm için ayrı, net ve güncel dokümantasyon hazırlayın. Sürüm notlarını (changelog) yayınlayın.
Geleceğe Yönelik İpuçları
API versiyonlama stratejinizi belirlerken, istemci türlerini (web, mobil, IoT) ve güncelleme alışkanlıklarını göz önünde bulundurun. Mobil uygulamalar için özellikle header versiyonlama veya URI versiyonlama daha uygun olabilir; çünkü query parametreleri bazı SDK'larda sorun çıkarabilir. Ayrıca, GraphQL gibi alternatifleri değerlendiriyorsanız, versiyonlama ihtiyacınız azalabilir; çünkü istemci tam olarak ihtiyacı olan alanları talep eder.
Unutmayın: API versiyonlama, uzun vadeli bir taahhüttür. Başlangıçta doğru stratejiyi seçmek, daha sonra baş ağrılarını önler. Sayfalama, hata yönetimi ve kimlik doğrulama gibi diğer API tasarım kararlarıyla birlikte düşünülmelidir.
Sık Sorulan Sorular
API versiyonlama neden önemlidir?
API versiyonlama, geriye dönük uyumluluğu korur ve istemci uygulamalarının bozulmamasını sağlar. Değişikliklerin kontrollü bir şekilde yayınlanmasına olanak tanır.
URI ve header versiyonlama arasındaki temel fark nedir?
URI versiyonlama, versiyon bilgisini URL'de taşır (örn. /v1/users) ve keşfedilebilirliği yüksektir. Header versiyonlama ise bilgiyi HTTP header'ına koyar, RESTful prensiplere daha uygundur ancak keşfedilmesi daha zordur.
Query parametreleriyle versiyonlama güvenli midir?
Genellikle önerilmez çünkü URL'ler önbelleğe alınırken sorun yaşanabilir ve API anahtarları gibi hassas bilgiler query string'de taşınırsa güvenlik riski oluşur. Prototip aşamasında geçici olarak kullanılabilir.
Eski API sürümlerini ne zaman kullanımdan kaldırmalıyım?
Yeni sürüm yayınlandıktan sonra en az 6-12 ay geçiş süresi tanıyın. Deprecation ve Sunset header'ları ile istemcileri bilgilendirin. Kullanım istatistiklerini takip ederek eski sürümleri kademeli olarak devre dışı bırakın.
Bir API'de kaç sürümü aynı anda desteklemeliyim?
Genellikle en fazla 2-3 sürümü aynı anda desteklemek mantıklıdır. Çok fazla sürüm bakım yükünü artırır. Eski sürümleri planlı bir şekilde kullanımdan kaldırarak sayıyı kontrol altında tutun.
