Bir REST API geliştirirken değişiklik kaçınılmazdır; yeni özellikler eklenir, eski alanlar kaldırılır veya iş mantığı yeniden düzenlenir. İstemcilerin uygulamanızı kullanmaya devam edebilmesi için etkili bir versiyonlama stratejisi şarttır. Peki, URI üzerinden mi, Header ile mi yoksa Query Parameter ile mi versiyonlamalısınız? Bu sorunun net bir cevabı yok; her yöntemin kendine özgü avantajları ve dezavantajları var.
Versiyonlama, API'nizin evrimini kontrol etmenizi sağlar ancak yanlış strateji, bakım kabusuna dönüşebilir. İstemcilerinizi kırmadan değişim yapabilmek için doğru yaklaşımı seçmek kritik öneme sahiptir.
API Versiyonlama Nedir ve Neden Gereklidir?
API versiyonlama, bir web servisinin farklı sürümlerini aynı anda yayında tutarak istemcilerin kendi hızlarında güncelleme yapmasına olanak tanır. Örneğin, bir mobil uygulamanın eski bir sürümü hâlâ API'nin v1'ini kullanırken, yeni sürüm v2'ye geçmiş olabilir. Versiyonlama olmadan, API'de yapılan kırıcı bir değişiklik (breaking change) tüm istemcileri anında etkiler ve bu genellikle istenmeyen bir durumdur.
Versiyonlama Olmadığında Karşılaşılan Sorunlar
- Kırıcı değişikliklerin kontrolsüz yayılması: İstemci beklemeden hata alır.
- Geri uyumluluk yükü: Eski istemcileri desteklemek için kodda karmaşık koşullar oluşur.
- Dökümantasyon karmaşası: Hangi endpoint'in hangi davranışı sergilediği belirsizleşir.
Üç Temel Versiyonlama Stratejisi
1. URI tabanlı versiyonlama (URL Path Versioning)
En yaygın yöntemdir: /api/v1/kullanicilar, /api/v2/kullanicilar. Her yeni sürüm için yeni bir path eklenir.
Avantajları:
- Açık ve sezgisel: Geliştiriciler URL'den hangi sürümü kullandığını hemen anlar.
- Önbellekleme kolaydır: Farklı URL'ler farklı önbellek anahtarları oluşturur.
- Tüm HTTP istemcileriyle uyumludur.
Dezavantajları:
- URI'nin anlamsal bütünlüğünü bozar: Kaynak tanımlayıcısına versiyon bilgisi eklenir.
- Bakım zorluğu: Çok sayıda sürüm biriktiğinde URL yapısı karmaşıklaşır.
- Yönlendirme (routing) katmanında ek yük oluşturur.
2. Header tabanlı versiyonlama (Custom Header)
Versiyon bilgisi HTTP header'ında taşınır: Accept: application/vnd.bizimblog.v2+json veya özel bir header (X-API-Version: 2).
Avantajları:
- URL temiz kalır, kaynak tanımlayıcısı değişmez.
- İçerik anlaşması (content negotiation) prensibiyle uyumludur.
- Birden fazla sürüm aynı URL altında yönetilebilir.
Dezavantajları:
- İstemcilerin header'ı ayarlaması gerekir, bu da testi ve hata ayıklamayı zorlaştırabilir.
- Tarayıcı tabanlı araçlarda (örneğin, fetch API) ek konfigürasyon gerektirir.
- Önbellekleme daha karmaşıktır: Aynı URL farklı header'lar için farklı yanıtlar üretebilir.
3. Query Parameter tabanlı versiyonlama
URL'ye parametre olarak eklenir: /api/kullanicilar?version=2
Avantajları:
- Kolay uygulanabilir ve esnektir.
- URL'de görünür olduğu için test edilmesi basittir.
- Varsayılan bir sürüm belirlemek mümkündür.
Dezavantajları:
- Query parameter'ın anlamsal olarak kaynağın bir parçası olmaması, REST ilkelerine aykırıdır.
- Önbellekleme proxy'leri genellikle query string'i dikkate almayabilir.
- URL'lerin karmaşıklaşmasına neden olur.
Hangi Stratejiyi Seçmelisiniz?
Seçim, önceliklerinize ve ekosisteminize bağlıdır. İşte birkaç senaryo:
- Genel kullanıma açık API'ler için: URI tabanlı versiyonlama en yaygın kabul gören yöntemdir. Açıklık ve basitlik sağlar. Örneğin, GitHub API'si bu yöntemi kullanır.
- İç sistemler veya mikroservisler için: Header tabanlı yaklaşım daha esnek olabilir, ancak ekibin bu konuda disiplinli olması gerekir.
- Basit veya geçici API'ler için: Query parameter işe yarayabilir, ancak uzun vadede bakımı zordur.
Not: Hiçbir strateji tek başına mükemmel değildir. Çoğu ekip, URI versiyonlamayı başlangıç için tercih eder ve gerektiğinde Header tabanlı bir geçiş stratejisi uygular.
Sık Yapılan Hatalar ve Kaçınılması Gerekenler
- Sadece ana sürüm numarası kullanmak: Küçük değişiklikler için alt sürüm veya tarih kullanmak daha esnektir. Örneğin,
/api/v2.1gibi. - Versiyonlamayı dökümantasyona yansıtmamak: Her sürüm için ayrı dökümantasyon hazırlamak zorunludur. Yoksa istemciler neyin değiştiğini bilemez.
- Eski sürümleri aniden kaldırmak: En azından bir geçiş dönemi (deprecation) planlanmalı ve istemciler bilgilendirilmelidir.
- Versiyon bilgisini veritabanında saklamak: Versiyon, veri modeliyle değil, API davranışıyla ilgilidir.
İyi Uygulama Örnekleri
Başarılı örnekler arasında Twitter API (Header tabanlı, daha sonra URI'ya geçti) ve Stripe API (Header tabanlı, date-based version) sayılabilir. Ayrıca, GitHub API URI tabanlı versiyonlama ile bilinir. Kendi API'niz için en iyi yaklaşımı belirlerken aşağıdaki noktaları göz önünde bulundurun:
- İstemcilerinizin teknik yeterliliği: Header desteği zorunlu mu, yoksa URL'den anlamak mı daha kolay?
- Önbellekleme altyapınız: CDN veya proxy kullanıyorsanız URL tabanlı daha iyi çalışabilir.
- Mevcut uyumluluk: Eski istemciler varsa, onları kırmamak için versiyonlamayı nasıl uyguluyorsunuz?
API tasarımında önemli bir diğer konu da veri getirme stratejileridir. Örneğin, liste sonuçlarını sayfalarken Cursor-Based Pagination REST API: Uygulama Rehberi ve Kontrol Listesi yazımızda imleç tabanlı sayfalama ile geleneksel offset sayfalama arasındaki farkı ve neden daha iyi bir seçenek olduğunu anlattık.
Güvenlik de API versiyonlama ile yakından ilişkilidir. Farklı sürümler farklı güvenlik politikalarına sahip olabilir. Mobil Uygulamalarda OAuth 2.0 ve PKCE ile Güvenli Kimlik Doğrulama: Adım Adım Rehber başlıklı içerik, kimlik doğrulama sürecinde versiyonlama ile nasıl başa çıkılacağına dair ipuçları veriyor.
Sonuç: Stratejinizi Netleştirin ve İstemcilerinizi Düşünün
API versiyonlama, teknik bir karar olmanın ötesinde, bir ürün yönetimi stratejisidir. İstemcilerinize ne kadar süreyle eski sürümleri destekleyeceğinizi, hangi değişikliklerin kırıcı olduğunu ve sürüm geçişlerini nasıl yöneteceğinizi netleştirmelisiniz. URI tabanlı versiyonlama pratik ve yaygın olsa da, header tabanlı yaklaşım daha temiz bir URL yapısı sunar. Kendi API'niz için en uygun yöntemi seçerken bu rehberdeki artı ve eksileri değerlendirin. Unutmayın: İyi bir versiyonlama, API'nizin uzun ömürlü olmasının anahtarıdır.
Sık Sorulan Sorular
REST API'de versiyonlama neden önemlidir?
Versiyonlama, API'de yapılan kırıcı değişikliklerin istemcileri anında etkilemesini önler. Farklı istemci sürümlerinin aynı anda çalışmasına izin vererek geçiş sürecini yönetilebilir kılar.
URI, header ve query parameter versiyonlama arasında hangisi daha iyidir?
Her yöntemin avantajı ve dezavantajı vardır. URI tabanlı en yaygın ve sezgiselken, header tabanlı URL'yi temiz tutar. Query parameter basit ama REST ilkelerine aykırıdır. Seçim, API'nizin kullanım senaryosuna bağlıdır.
API versiyonlarken sık yapılan hatalar nelerdir?
En yaygın hatalar arasında sadece ana sürüm numarası kullanmak, eski sürümleri aniden kaldırmak, dökümantasyonu güncellememek ve versiyon bilgisini veritabanında saklamak yer alır.
Header tabanlı versiyonlama için hangi header kullanılmalı?
Genellikle 'Accept' header'ı içerik anlaşması için kullanılır (örneğin, 'application/vnd.bizimblog.v2+json'). Alternatif olarak özel bir header (örneğin, 'X-API-Version') da tercih edilebilir.
Eski API sürümlerini ne zaman kaldırmalıyım?
Eski sürümleri en az bir geçiş dönemi boyunca destekleyin. Kullanıcıları önceden bilgilendirin, dökümantasyonda deprecation notu ekleyin ve yeterli zaman tanıdıktan sonra kaldırın.
