API versiyonlama, mevcut istemcileri bozmadan API'de değişiklik yapmanın temel yoludur. Hangi yöntemi seçmelisiniz? URL path, header veya sorgu parametresi… Her birinin güçlü ve zayıf yönleri vardır. Bu yazıda, üç ana versiyonlama stratejisini karşılaştıracak, doğru bağlamda nasıl kullanılacağını ve sık yapılan hataları ele alacağız.
URL Path Versiyonlama Nedir?
Bu yöntemde API sürümü URL'nin bir parçası olarak belirtilir. Örneğin: /api/v1/users ve /api/v2/users. En yaygın kullanılan yaklaşımdır çünkü açık ve keşfedilmesi kolaydır.
Avantajları
- Basit ve anlaşılır: Geliştiriciler URL'den sürümü hemen görebilir.
- Önbelleğe alma kolaydır: Farklı sürümler farklı URL'ler olduğu için önbellek anahtarları doğal olarak ayrışır.
- API anahtarı veya yetkilendirme gerektirmez; herkes doğrudan erişebilir.
Dezavantajları
- URL'ler zamanla kirlenebilir: Çok sayıda sürüm birikirse yönetimi zorlaşır.
- Semantik versiyonlama zordur: Genelde büyük (major) sürüm numarası kullanılır; minor ve patch için ayrı URL uygun olmaz.
- REST prensipleriyle çelişebilir: Kaynak tanımlayıcının değişmesi, REST'in tek tip arayüz ilkesini zorlar.
Header Versiyonlama (Accept Header veya Custom Header)
Sürüm bilgisi HTTP başlıklarına gömülür. En yaygın iki yöntem: Accept header ile medya tipi belirtmek (ör: Accept: application/vnd.example.v1+json) veya özel bir header (ör: X-API-Version: 1) kullanmaktır.
Avantajları
- URL temiz kalır: Aynı endpoint farklı sürümleri başlıkla yönetir.
- İstemciler başlığı değiştirerek sürüm geçişi yapabilir; URL değişmez.
- Medya tipi tabanlı versiyonlama (Accept header) REST ilkelerine daha uygundur.
Dezavantajları
- Keşfedilebilirlik zordur: Geliştiriciler sürümü görmek için başlıklara bakmak zorunda.
- Önbelleğe alma karmaşıklığı: Vary header yapılandırması gerektirebilir.
- Custom header kullanımı standart değildir ve bazı araçlar tarafından desteklenmeyebilir.
Sorgu Parametresi Versiyonlama
Sürüm, URL'de sorgu parametresi olarak eklenir: /api/users?version=1. Genellikle en az tercih edilen yöntemdir.
Avantajları
- Uygulaması çok basittir: Mevcut API'ye kolayca eklenebilir.
- Varsayılan sürüm atanabilir.
Dezavantajları
- Önbellek anahtarları sorgu parametrelerini içermezse farklı sürümler aynı önbellekten servis edilebilir.
- URL'ler karmaşıklaşır ve parametre ezilmelerine açıktır.
- İstemciler parametreyi unutursa varsayılan sürüm kullanılır; bu da sürpriz hatalara yol açabilir.
Hangi Durumda Hangi Yöntem?
Seçim, API'nizin kullanım senaryosuna bağlıdır. Aşağıdaki tablo karar vermenize yardımcı olabilir:
| Kriter | URL Path | Header (Accept) | Sorgu Parametresi |
|---|---|---|---|
| Keşfedilebilirlik | Yüksek | Düşük | Orta |
| Önbelleğe Alma | Kolay | Orta | Zor |
| REST Uyumu | Orta | Yüksek | Düşük |
| Uygulama Kolaylığı | Kolay | Orta | Çok Kolay |
| Minor/Patch Sürüm | Zor | Kolay | Orta |
Genel olarak, URL path versiyonlama kamuya açık ve basit API'ler için önerilirken, Accept header versiyonlama uzun vadeli ve REST prensiplerine sıkı sıkıya bağlı sistemler için daha uygundur. Sorgu parametresi ise geçici çözümler veya iç API'ler için düşünülebilir.
Sık Yapılan Hatalar
- Çok sık versiyon değiştirmek: Her küçük değişiklikte yeni sürüm çıkarmak istemci yorgunluğuna yol açar. Minor değişiklikler için backward-compatible olmaya çalışın.
- Eski sürümleri hemen kaldırmak: İstemcilerin geçiş yapması için yeterli süre tanıyın. En az 6-12 ay destek politikası belirleyin.
- Dökümantasyonu ihmal etmek: Her sürümün değişikliklerini net bir changelog ile belgeleyin.
- Versiyonlamayı hiç kullanmamak: İlk sürümden itibaren bir versiyonlama stratejisi belirleyin; sonradan eklemek zordur.
Alternatif Yaklaşımlar: Sürümsüz API
Bazı ekipler, sürekli geriye uyumluluk sağlayarak sürüm numarası kullanmamayı tercih eder. Bu, ancak çok kontrollü bir ortamda ve güçlü bir test altyapısıyla mümkündür. Genelde yeni alanlar ekleyerek, mevcut alanları değiştirmeyerek ve isteğe bağlı parametrelerle uyumluluk korunabilir. Ancak büyük değişiklikler kaçınılmaz olduğunda yine bir sürümleme mekanizması gerekir.
API tasarımınızda doğru sayfalama stratejisi de önemlidir. Bu konuda REST API Sayfalama Stratejileri yazımızı inceleyebilirsiniz. Ayrıca, mikro servis mimarilerinde versiyonlama daha da kritik hale gelir; Micro Frontends ile modüler yapılar oluştururken API uyumluluğuna dikkat etmelisiniz.
Sonuç
API versiyonlama stratejisi seçerken projenizin ihtiyaçlarını, istemci tabanını ve bakım yükünü değerlendirin. URL path basitliği, header versiyonlama REST uyumu sunar; sorgu parametresi ise son çare olmalıdır. Unutmayın, iyi bir versiyonlama planı API'nizin uzun ömürlü olmasını sağlar.
Sık Sorulan Sorular
API versiyonlama neden gereklidir?
İstemcileri bozmadan API'de değişiklik yapabilmek için gereklidir. Farklı sürümler sayesinde eski istemciler çalışmaya devam ederken yeni özellikler eklenebilir.
URL path versiyonlama mı yoksa header versiyonlama mı daha iyi?
URL path daha basit ve keşfedilebilirdir; header versiyonlama ise REST prensiplerine daha uygun ve URL'yi temiz tutar. Kamuya açık API'lerde URL path, uzun vadeli ve sıkı kontrollü sistemlerde header önerilir.
Sorgu parametresi ile versiyonlama ne zaman kullanılmalı?
Genellikle önerilmez. Ancak mevcut bir API'ye hızlıca sürüm eklemek gerektiğinde veya iç API'lerde geçici çözüm olarak kullanılabilir.
Eski API sürümlerini ne zaman kaldırmalıyım?
En az 6-12 ay önceden duyuru yaparak ve istemcilerin geçiş yapması için zaman tanıyarak kaldırılmalıdır. Deprecation header ile kullanıcıları bilgilendirmek iyi bir uygulamadır.
Sürümsüz (versionless) API mümkün mü?
Evet, ancak tüm değişikliklerin geriye uyumlu olması gerekir. Bu, yeni alanlar ekleyip mevcut alanları değiştirmemekle sağlanabilir. Büyük değişikliklerde yine bir sürümleme gerekebilir.
