API versiyonlama, REST API'lerin uzun vadeli sürdürülebilirliği için kritik bir tasarım kararıdır. Değişen gereksinimler karşısında mevcut istemcileri bozmadan yeni özellikler eklemek veya eski davranışları değiştirmek için bir sürüm yönetimi stratejisi şarttır. Bu yazıda, en yaygın üç versiyonlama yaklaşımını (URI, header ve query parametresi) karşılaştıracak, her birinin avantaj ve dezavantajlarını inceleyecek ve projeniz için doğru seçimi yapmanıza yardımcı olacak pratik bir kontrol listesi sunacağız.
Neden API Versiyonlama Gerekli?
Bir API yayınlandıktan sonra, istemciler (mobil uygulamalar, web ön yüzleri, üçüncü parti servisler) belirli bir davranışa güvenir. Zamanla yeni özellikler eklemek veya mevcut uç noktaların davranışını iyileştirmek isteyebilirsiniz. Versiyonlama olmadan, yapılan her değişiklik mevcut istemcileri bozma riski taşır. Ayrıca, farklı istemciler farklı hızlarda güncellenir; eski bir mobil uygulama sürümü hâlâ eski API davranışını beklerken, yeni sürüm yeni özelliklerden yararlanmak isteyebilir. Bu senaryoyu yönetmek için Node.js ile JWT Kimlik Doğrulama rehberinde olduğu gibi, API'nizin güvenliğini de sürümler arasında tutarlı tutmanız gerekir.
Üç Temel Versiyonlama Yaklaşımı
REST API'lerde yaygın olarak kullanılan üç ana versiyonlama yöntemi vardır: URI'de versiyon, özel başlık (header) ile versiyon ve sorgu parametresi ile versiyon. Her birini ayrıntılı olarak inceleyelim.
1. URI'de Versiyonlama (URL Path Tabanlı)
En yaygın ve anlaşılması kolay yöntemdir. API sürümü, uç noktanın URL yolunun bir parçası olarak belirtilir. Örnek:
GET /api/v1/kullanicilar
GET /api/v2/kullanicilarAvantajları:
- Açık ve keşfedilebilir: İstemciler, hangi sürümü kullandıklarını URL'den hemen görebilir.
- HTTP önbellekleme ile uyumludur: Farklı sürümler farklı URL'ler olduğu için önbellek çakışması olmaz.
- Basit ve yaygın kabul görmüş: Birçok büyük API (GitHub, Twitter) bu yöntemi kullanır.
Dezavantajları:
- URI kirliliği: Sürüm bilgisi URL'nin anlamlı kısmına dahil değildir ve kaynak tanımlayıcıyı şişirir.
- Bakım zorluğu: Her yeni sürüm için yeni Route tanımları gerekir.
- Semantik olmayan: REST prensiplerine göre URL'ler kaynakları temsil etmeli, sürüm bilgisi taşımamalıdır.
2. Header ile Versiyonlama (Özel Başlık Tabanlı)
Sürüm bilgisi, HTTP istek başlığında özel bir alan olarak taşınır. Örnek:
GET /api/kullanicilar
Accept: application/vnd.example.v2+jsonveya X-API-Version: 2 gibi özel bir başlık da kullanılabilir.
Avantajları:
- URL'ler temiz kalır, kaynak tanımlayıcılar değişmez.
- REST prensiplerine daha uygundur: Sürüm, içerik anlaşması (content negotiation) mekanizmasının bir parçasıdır.
- Farklı sürümler için farklı medya tipleri kullanılabilir.
Dezavantajları:
- Keşfedilebilirliği zordur: Tarayıcıdan veya basit bir curl komutuyla test etmek için ek başlık eklemek gerekir.
- Proxy ve önbellek uyumluluğu daha karmaşıktır: Vary başlığı doğru ayarlanmalıdır.
- İstemci tarafında ek kod gerektirir: Her istekte başlığı göndermek zorunludur.
3. Query Parametresi ile Versiyonlama
Sürüm, URL'de bir sorgu parametresi olarak belirtilir. Örnek:
GET /api/kullanicilar?version=2Avantajları:
- Uygulaması kolaydır: URL'ye parametre eklemek yeterlidir.
- Hızlı test edilebilir: Tarayıcı adres çubuğundan kolayca değiştirilebilir.
Dezavantajları:
- URI'yi şişirir, anlamsal olarak URL'nin parçası haline gelir.
- Önbellekleme karmaşıklaşır: Aynı kaynak farklı versiyon parametreleriyle farklı yanıtlar döndürebilir.
- HTTP standartlarına aykırı olabilir: Parametreler kaynağı tanımlamalı, sürüm gibi meta bilgileri taşımamalıdır.
Hangi Stratejiyi Seçmelisiniz?
Seçim, projenizin ihtiyaçlarına bağlıdır. URI tabanlı yaklaşım, basitlik ve keşfedilebilirlik isteyen ekipler için idealdir. Header tabanlı yaklaşım, REST uyumu ve temiz URL'ler isteyen daha olgun API'ler için uygundur. Query parametresi ise hızlı prototipleme veya iç kullanım için kullanılabilir. Kararınızı desteklemek için Node.js'de N+1 Problemi çözümünde olduğu gibi, performans ve bakım maliyetlerini de hesaba katın.
Pratik İpuçları ve Kontrol Listesi
Versiyonlama stratejinizi uygularken aşağıdaki maddeleri kontrol edin:
- Versiyon numarası biçimini belirleyin: Genellikle
v1,v2gibi tam sayılar kullanılır. Anlamsal sürümleme (semver) API'ler için tavsiye edilmez çünkü alt sürüm farkları istemciler için anlamlı değildir. - Varsayılan sürüm tanımlayın: İstemci sürüm belirtmezse en son kararlı sürümü döndürecek bir varsayılan belirleyin. Ancak bu, istemcilerin bozulmasına yol açabileceği için dikkatli kullanılmalıdır.
- Eski sürümleri ne zaman kaldıracağınızı planlayın: Her sürümün bir ömrü olmalıdır. Kullanımdan kaldırma (deprecation) politikası oluşturun ve istemcilere yeterli geçiş süresi tanıyın.
- Dokümantasyonu güncel tutun: Her sürüm için ayrı dokümantasyon sağlayın. Değişiklikleri net bir şekilde belirtin.
- Header yaklaşımı kullanıyorsanız Vary başlığını ayarlayın: Önbelleklerin farklı sürümleri doğru şekilde yönetmesi için
Vary: Acceptgibi başlıklar ekleyin. - İstemci geriye dönük uyumluluğu test edin: Yeni bir sürüm yayınlamadan önce, eski istemcilerin yeni sürümle (eğer değişiklik yoksa) veya eski sürümle çalışmaya devam ettiğini doğrulayın.
- Kullanım istatistiklerini izleyin: Hangi istemcilerin hangi sürümü kullandığını takip edin. Bu, eski sürümleri ne zaman kaldırabileceğinize karar vermenize yardımcı olur.
- Orta katmanda versiyon yönlendirmesi kullanın: Bir API ağ geçidi (API gateway) ile gelen istekleri ilgili sürüm hizmetine yönlendirin. Bu, arka uç servislerinizi versiyonlama karmaşıklığından korur.
Versiyonlama ile İlgili Sık Yapılan Hatalar
- Tüm API'yi aynı anda versiyonlamak: Belirli uç noktalar veya kaynaklar için versiyonlama yapmak daha esnektir. Tüm API'yi tek bir sürümle yönetmek gereksiz değişikliklere yol açar.
- Kırıcı değişiklikleri küçük sürümlerde yapmak: Küçük değişiklikler (örneğin bir alan eklemek) genellikle kırıcı değildir. Ancak alan silmek, tür değiştirmek gibi değişiklikler yeni bir ana sürüm gerektirir.
- Versiyon numarasını unutmak: İstemcilerin versiyon bilgisini hatasız göndermesini beklemek yerine, varsayılan bir sürüm atayın ve hatırlatıcı başlıklar ekleyin.
Sonuç
API versiyonlama stratejisi, projenizin büyüklüğüne, istemci ekosistemine ve ekip tercihlerine göre şekillenir. URI tabanlı yaklaşım hızlı başlangıçlar için uygunken, header tabanlı yaklaşım temiz ve REST uyumlu bir tasarım sunar. Query parametresi ise ara çözümlerde kullanılabilir. Hangi yöntemi seçerseniz seçin, net bir politika belirleyin ve dokümantasyonu güncel tutun. Ayrıca, CommonJS vs ES Modules karşılaştırmasında olduğu gibi, teknoloji seçimlerinizi proje ihtiyaçlarına göre yapın.
Sık Sorulan Sorular
API versiyonlama neden önemlidir?
API versiyonlama, mevcut istemcileri bozmadan yeni özellikler eklemenize veya davranış değişiklikleri yapmanıza olanak tanır. Farklı istemci sürümlerinin uyumlu şekilde çalışmasını sağlar ve geriye dönük uyumluluğu yönetmeyi kolaylaştırır.
URI versiyonlama mı header versiyonlama mı daha iyi?
URI versiyonlama, basit ve keşfedilebilir olduğu için küçük ve orta ölçekli projelerde yaygın olarak tercih edilir. Header versiyonlama ise REST prensiplerine daha uygun olup temiz URL'ler sağlar, ancak istemci tarafında ek başlık gönderme zorunluluğu getirir. Seçim, projenizin ihtiyaçlarına ve ekip deneyimine bağlıdır.
REST API'de versiyon numarası nasıl belirlenmeli?
Genellikle tamsayı sürüm numaraları (v1, v2) kullanılır. Anlamsal sürümleme (semver) API'ler için önerilmez çünkü küçük değişiklikler bile istemciler için kırıcı olabilir. Sürüm numarasını net ve anlaşılır tutmak, istemcilerin hangi sürümü kullandığını kolayca anlamasını sağlar.
Eski API sürümlerini ne zaman kaldırmalıyım?
Eski sürümleri kaldırmadan önce, istemcilere yeterli geçiş süresi tanıyın. Genellikle 6 ay ile 1 yıl arasında bir süre önerilir. Kullanımdan kaldırma (deprecation) başlıkları ekleyerek istemcileri bilgilendirin ve kullanım istatistiklerini izleyerek düşük kullanımlı sürümleri temizleyin.
Query parametresi ile versiyonlama ne zaman kullanılmalı?
Query parametresi ile versiyonlama, hızlı prototipleme veya dahili API'ler için uygun olabilir. Ancak, önbellekleme ve URI anlamlılığı açısından sorunlar yaratabileceği için üretim ortamında genellikle URI veya header tabanlı yaklaşımlar tercih edilir.
