REST API'lerde Versiyonlama Stratejileri: URI vs Header vs Query Param Karşılaştırması

REST API'ler zaman içinde değişir. İstemcileri kırmadan yeni özellikler eklemek veya mevcut davranışları değiştirmek için versiyonlama kritik bir tasarım kararıdır. API versiyonlama, farklı sürümlerdeki uyumsuz değişiklikleri yönetmenizi sağlar. Bu yazıda en yaygın üç versiyonlama stratejisini — URI tabanlı, Header tabanlı ve Query Param tabanlı — karşılaştırmalı olarak analiz edeceğiz.

API Versiyonlama Neden Gereklidir?

Bir REST API geliştirirken, istemcilerin mevcut entegrasyonlarını bozmadan değişiklik yapabilmek için versiyonlama şarttır. Uyumsuz değişiklikler (breaking changes) yapıldığında, eski istemciler çalışmaya devam etmeli, yeni istemciler ise güncel sürümü kullanabilmelidir. Versiyonlama olmazsa, her değişiklik tüm istemcilerin güncellenmesini zorunlu kılar. REST API'lerde Input Validation gibi diğer en iyi uygulamalarla birlikte versiyonlama da planlanmalıdır.

Üç Temel Versiyonlama Stratejisi

1. URI Tabanlı Versiyonlama

En yaygın ve anlaşılması kolay yöntemdir. API sürümü URL yoluna eklenir: https://api.example.com/v1/users. Bu yaklaşım, sürümü doğrudan endpoint'te gösterdiği için keşfedilebilirliği yüksektir.

• Avantajları: Basit, net, herkes tarafından anlaşılır; tarayıcıdan test etmesi kolay; önbellek anahtarları otomatik olarak farklılaşır.
• Dezavantajları: URL yapısı kalabalıklaşır; sürümü değiştirmek için istemcinin URL'yi güncellemesi gerekir; bazı REST puristleri tarafından URI'nın kaynağı temsil etmesi gerektiği için eleştirilir.

2. Header Tabanlı Versiyonlama

Sürüm bilgisi HTTP header'ları ile taşınır. Yaygın olarak Accept header'ı kullanılır: Accept: application/vnd.example.v2+json. Alternatif olarak özel bir header da eklenebilir: API-Version: 2.

• Avantajları: URL temiz kalır; REST prensiplerine daha uygundur; header'da daha fazla meta veri (medya türü) taşınabilir.
• Dezavantajları: Keşfedilebilirliği düşüktür; tarayıcıdan test etmesi zordur; önbellek anahtarları header'ı içermiyorsa sorun çıkabilir; istemci tarafında ekstra kod gerektirir.

3. Query Param Tabanlı Versiyonlama

Sürüm bilgisi sorgu parametresi olarak iletilir: https://api.example.com/users?version=2. Bazı API'ler api-version parametresini kullanır.

• Avantajları: URI tabanlı kadar basit; önbellek anahtarlarına kolayca dahil edilebilir; parametre varsayılan değer atanarak eski istemciler desteklenebilir.
• Dezavantajları: URL'de anlamsız bir parametre; sorgu dizisinin şişmesi; RESTful olmayan bir yaklaşım; yanlışlıkla ihmal edilebilir.

Karşılaştırma Tablosu

Hangi Strateji Ne Zaman Kullanılmalı?

Seçim, API'nizin hedef kitlesine ve kullanım senaryosuna bağlıdır. İşte bazı öneriler:

• URI tabanlı, özellikle üçüncü taraf geliştiricilere açık, keşfedilebilirliğin önemli olduğu genel API'ler için idealdir. Örneğin, REST API'lerde sayfalama yaparken sayfalama stratejileri gibi net URL yapıları tercih edilir.
• Header tabanlı, REST prensiplerine sıkı sıkıya bağlı, URL'yi temiz tutmak isteyen iç API'ler veya medya türüne dayalı içerik anlaşması yapan sistemler için uygundur.
• Query param tabanlı, geçici bir çözüm olarak veya mevcut API'ye sonradan versiyon eklenirken kullanılabilir. Ancak uzun vadede önerilmez.

En İyi Uygulamalar ve Sık Yapılan Hatalar

Yapılması Gerekenler

• Versiyonlama stratejinizi API dokümantasyonunda açıkça belirtin.
• Eski sürümleri belirli bir süre (örneğin, 6 ay) destekleyip sonra kullanımdan kaldırma (deprecation) politikası uygulayın.
• Header tabanlı versiyonlamada Content-Type veya Accept header'ını kullanın, özel header'lardan kaçının.
• Önbellek katmanında header'ları da dikkate alacak şekilde konfigürasyon yapın.

Kaçınılması Gerekenler

• Versiyon numarasını ürün sürümüyle karıştırmayın; API versiyonu bağımsız olmalıdır.
• Query param tabanlı versiyonlamada varsayılan sürümü belirlemezseniz eski istemciler kırılabilir.
• URI tabanlı versiyonlamada sürümü kaynağın bir parçasıymış gibi göstermekten kaçının (/users/v1 yerine /v1/users tercih edilir).
• Versiyonlamayı hiç yapmamak büyük bir hatadır; en azından URI tabanlı basit bir çözüm uygulayın.

Örnek Vaka Çalışması: URI Tabanlı Versiyonlama

Bir e-ticaret API'si düşünelim. Başlangıçta /v1/products endpoint'i ürün adı ve fiyat döndürüyordu. Yeni sürümde /v2/products ile birlikte stok bilgisi de ekleniyor. Eski istemciler /v1/products kullanmaya devam ederken, yenileri /v2/products ile stok verisine erişir. Bu şekilde geriye dönük uyumluluk sağlanır. Uzun vadede /v1 kullanımdan kaldırılabilir.

Sonuç

REST API versiyonlama stratejisi seçerken, API'nizin doğası, istemci kitlesi ve operasyonel ihtiyaçlarınızı göz önünde bulundurun. URI tabanlı versiyonlama basitliği ve yaygınlığı ile en güvenli seçenektir. Header tabanlı yaklaşım daha RESTful bir çözüm sunar ancak ek yük getirir. Query param ise belirli durumlar için kullanışlıdır. Testler yaparak ve dokümantasyonu güncel tutarak istemcilerinizin sorunsuz geçiş yapmasını sağlayabilirsiniz.

Sık Sorulan Sorular

REST API'de versiyonlama neden önemlidir?

Versiyonlama, API'de yapılan uyumsuz değişikliklerin mevcut istemcileri etkilemeden uygulanmasını sağlar. İstemcilerin kırılmasını önler ve farklı sürümlerin aynı anda çalışmasına olanak tanır.

URI tabanlı versiyonlama mı daha iyi yoksa header tabanlı mı?

URI tabanlı versiyonlama keşfedilebilirlik ve test kolaylığı açısından daha basittir. Header tabanlı ise REST prensiplerine daha uygundur. Seçim, API'nizin kullanım senaryosuna bağlıdır.

Query parametresi ile versiyonlama yapılabilir mi?

Evet, ancak önerilmez. URL'yi karmaşıklaştırır ve RESTful değildir. Geçici çözüm olarak kullanılabilir ancak uzun vadede URI veya header tabanlı yöntemler tercih edilmelidir.

Eski API sürümlerini ne zaman kullanımdan kaldırmalıyım?

Eski sürümleri kullanımdan kaldırmadan önce istemcilere en az 6 ay gibi bir geçiş süresi tanıyın. Kullanımdan kaldırma duyurusunu API dokümantasyonunda ve header'larla yapın.