REST API geliştirirken karşılaşılan en kritik kararlardan biri versiyonlama stratejisidir. API'niz zamanla değişir, yeni özellikler eklenir veya mevcut davranışlar güncellenir. İstemcileri bozmadan bu değişiklikleri yönetmek için bir versiyonlama yöntemi seçmeniz gerekir. En yaygın üç yaklaşım URL tabanlı (path), header tabanlı ve query parametresi tabanlı versiyonlamadır. Bu yazıda her birini avantajları, dezavantajları ve uygun kullanım senaryolarıyla ele alıyoruz.
URL Tabanlı Versiyonlama (Path Versioning)
Bu yöntemde API sürümü URL'nin bir parçası olarak belirtilir. Örnek: /api/v1/users, /api/v2/users. En yaygın kullanılan stratejidir çünkü oldukça basit ve keşfedilebilirdir. İstemciler, hangi sürümü kullandıklarını açıkça görür. Ancak, URL'de versiyon numarası olması REST prensiplerine aykırı olduğu yönünde eleştiriler alır (URI'ler belirli bir kaynağı temsil etmeli, sürümü değil). Ayrıca, her yeni sürüm yeni bir URL yapısı gerektirir ve bu da bakım maliyetini artırabilir.
Avantajları
- Kolay anlaşılır ve test edilebilir.
- İstemci tarafında özel bir header veya parametre işleme gerekmez.
- Web tarayıcıları, önbellekler ve ara yazılımlarla sorunsuz çalışır.
Dezavantajları
- Kaynak URI'si değişir; REST kaynaklarının benzersiz bir URI ile temsil edilmesi prensibini ihlal edebilir.
- Sürümlerin çoğalması URL yönetimini karmaşıklaştırabilir.
- Gerçekten kullanılmayan eski sürümlerin temizlenmesi zorlaşabilir.
Header Tabanlı Versiyonlama
Sürüm bilgisi HTTP header'ları taşınır. Yaygın uygulamalar: Accept: application/vnd.api.v1+json (Content negotiation) veya özel bir header API-Version: 1. Bu yöntem URI'yi temiz tutar ancak istemcilerin her istekte header'ı eklemesini gerektirir. Ayrıca, keşfedilebilirliği düşüktür; geliştiriciler hangi sürümün kullanıldığını anlamak için dokümantasyon incelemelidir.
Avantajları
- URI kararlı kalır, REST prensiplerine daha uygundur.
- Sürüm yönetimi merkezi bir noktada yapılabilir (örneğin API gateway).
- İstemci belirli bir sürümü talep ederken esnek davranabilir.
Dezavantajları
- İstemci tarafında daha fazla iş yükü: header'ları ekleme ve yönetme.
- Test ve hata ayıklama sırasında header'ları görmek URL'den daha zordur.
- Tarayıcı tabanlı araçlarla (örneğin cURL'de header ekleme) kullanımı daha az sezgiseldir.
Query Parametresi ile Versiyonlama
Örnek: /api/users?version=1. Bu yaklaşım URL'de sürümü sorgu parametresi olarak taşır. URL tabanlıya benzer ancak parametre kullanımı bazı çevrelerce daha esnek kabul edilir. Ancak önbellek stratejileriyle uyumsuzluk yaşanabilir (farklı sorgu parametreleri aynı kaynağı göstermez). Ayrıca, karmaşık filtrelere sahip API'lerde versiyon parametresi diğer parametrelerle karışabilir.
Avantajları
- URL yapısı basit ve esnektir.
- Header tabanlı yönteme göre daha kolay test edilir.
- Varsayılan sürüm belirlenebilir (parametre yoksa son sürüm).
Dezavantajları
- Sorgu parametreleri genellikle kaynağı değil, filtrelemeyi temsil eder; sürüm bir filtre değildir.
- Önbellek proxy'leri aynı URL'leri farklı sürümler için karıştırabilir.
- API dokümantasyonunda ek bir parametre olarak belirtilmesi gerekir.
Hangi Stratejiyi Seçmelisiniz?
| Kriter | URL Tabanlı | Header Tabanlı | Query Parametresi |
|---|---|---|---|
| Kolaylık | Yüksek | Orta | Yüksek |
| REST Uyumluluğu | Düşük | Yüksek | Orta |
| Keşfedilebilirlik | Yüksek | Düşük | Orta |
| Test Edilebilirlik | Kolay | Zor | Kolay |
| Önbellek Uyumu | İyi | İyi | Kötü |
| Önerilen Kullanım | Hızlı prototip, küçük ekipler | Büyük, uzun ömürlü API'ler | Geçiş dönemleri, eski sistemler |
Seçim, API'nizin hedef kitlesine ve ekosistemine bağlıdır. URL tabanlı basitliği nedeniyle popülerdir; header tabanlı daha temiz bir tasarım sunar; query parametresi ise ara bir çözümdür. Genel kabul, public API'ler için URL veya header tercih edilirken, internal API'lerde query parametresinin kullanılabileceği yönündedir.
Sık Yapılan Hatalar ve Dikkat Edilmesi Gerekenler
- Versiyonlamayı unutmak: API değişiklikleri kaçınılmazdır; baştan bir strateji belirleyin.
- Çok sık versiyon değiştirmek: Her küçük değişiklik yeni sürüm gerektirmez; backward-compatible değişiklikler için versiyon atlamayın.
- Eski sürümleri sonsuza kadar desteklemek: Belirli bir yaşam döngüsü belirleyin (örneğin 2 yıl) ve kullanıcıları bilgilendirin.
- Versiyon bilgisini cache anahtarı olarak kullanmamak: Özellikle query parametresinde versiyon kullanıyorsanız cache stratejinizi buna göre düzenleyin.
- Dokümantasyonu güncel tutmamak: Her sürüm için ayrı dokümantasyon hazırlayın ve eski sürümlerin dokümanlarını arşivleyin.
API Güvenliği ve Diğer Hususlar
Versiyonlama stratejiniz ne olursa olsun, API güvenliği ihmal edilmemelidir. JWT Access ve Refresh Token Yönetimi yazımızda anlattığımız gibi, token tabanlı kimlik doğrulama ile API'nizi koruyun. Ayrıca, istek sınırlandırması (rate limiting) da API kararlılığı için kritiktir. API Rate Limiting Algoritmaları karşılaştırmamızda bu konuyu detaylandırdık. İstemci tarafında hata yönetimini iyileştirmek için Axios Interceptor ile HTTP Hata Yönetimi rehberimizi inceleyebilirsiniz.
Sonuç olarak, REST API versiyonlama stratejisi projenizin ihtiyaçlarına göre belirlenmelidir. URL tabanlı basit ve anlaşılırdır; header tabanlı daha temiz ve REST uyumludur; query parametresi ise esneklik sunar. Hangi yöntemi seçerseniz seçin, tutarlı olun ve değişiklikleri iyi belgeleyin.
Sık Sorulan Sorular
REST API'de versiyonlamayı URL'de mi, header'da mı yoksa query parametresinde mi yapmalıyım?
Bu tamamen API'nizin kullanım senaryosuna bağlı. URL tabanlı basit ve yaygındır; header tabanlı REST prensiplerine daha uygundur; query parametresi ise esneklik sunar. Public API'ler için genellikle URL veya header önerilir.
API versiyonlamada en sık yapılan hata nedir?
En sık yapılan hata, hiç versiyonlama yapmamak veya çok sık versiyon değiştirmek. Geriye uyumlu değişiklikler yeni sürüm gerektirmez. Ayrıca eski sürümleri belirli bir yaşam döngüsü sonunda kaldırmalısınız.
Query parametresi ile versiyonlama önbellek sorunlarına yol açar mı?
Evet, query parametresi kullanımı önbellek stratejilerini karmaşıklaştırabilir. Farklı sürümler farklı sorgu parametreleriyle aynı URL'yi kullandığından, önbellek proxy'leri doğru sürümü önbelleğe almayabilir.
Aynı anda birden fazla versiyonlama yöntemi kullanılabilir mi?
Teknik olarak mümkündür, ancak önerilmez. Karmaşıklığı artırır ve istemcilerin hangi yöntemi kullanacağı konusunda kafa karışıklığı yaratır. Tek bir tutarlı yöntem seçmek daha iyidir.
Eski API sürümlerini ne zaman kullanımdan kaldırmalıyım?
Eski sürümler için bir yaşam döngüsü belirleyin (örneğin, yeni sürüm yayınlandıktan 1-2 yıl sonra). Kullanıcıları önceden bilgilendirin ve geçiş için yeterli süre tanıyın. Kullanım istatistiklerine göre de karar verebilirsiniz.
