API versiyonlama, REST servislerinde geriye dönük uyumluluğu korurken yeni özellikler eklemenin anahtarıdır. Peki URI tabanlı mı, header mı yoksa content negotiation yoluyla mı versiyonlamalısınız? Bu yazıda en yaygın üç stratejiyi uygulama örnekleriyle karşılaştırıyor, her birinin avantajlarını ve dikkat edilmesi gereken noktaları pratik ipuçları eşliğinde sunuyoruz.
API Versiyonlama Neden Önemlidir?
Bir API yayınlandıktan sonra istemciler (mobil uygulamalar, web uygulamaları, üçüncü parti entegrasyonlar) belirli bir sözleşmeye güvenir. Yeni özellikler eklerken veya mevcut davranışları değiştirirken bu sözleşmeyi bozmamak için versiyonlama şarttır. Aksi halde eski istemciler bozulur ve bu da ciddi kullanıcı kaybına yol açar. Bu nedenle REST API’lerde Etkili Hata Yönetimi kadar versiyonlama da projenin sürdürülebilirliği için kritiktir.
Üç Ana Versiyonlama Stratejisi
1. URI Tabanlı Versiyonlama (Path-based)
En yaygın ve anlaşılması en kolay yöntemdir. API sürümü doğrudan URL yolunda belirtilir:
GET /api/v1/kullanicilar
GET /api/v2/kullanicilar
Avantajları:
- Keşfedilebilirliği yüksektir; istemciler hangi sürümü kullandığını URL'den görebilir.
- Cache mekanizmalarıyla sorunsuz çalışır.
- HTTP yönlendirmeleri kolayca yapılabilir.
Dezavantajları:
- URL'lerin kirlenmesine yol açar; REST'in temel prensiplerine aykırı olduğunu savunanlar vardır (kaynağın temsil yeteneği).
- Her sürüm için farklı kod dalları yönetmek gerekebilir.
Pratik ipucu: URI versiyonlama kullanıyorsanız, sürüm numarasını v1, v2 gibi tam sayılarla belirtin. Noktalı sürümlerden (v1.1) kaçının; çünkü değişikliklerin kırıcı olup olmadığı konusunda kafa karışıklığı yaratır. Geriye dönük uyumlu değişiklikler için sürüm yükseltmeyin, sadece kırıcı değişikliklerde yeni sürüm çıkarın.
2. Header Tabanlı Versiyonlama (Accept Header veya Custom Header)
Sürüm bilgisi HTTP başlıklarında taşınır. İki yaygın yaklaşım vardır:
- Accept Header ile Content Negotiation: İstemci,
Accept: application/vnd.myapi.v2+jsonşeklinde bir medya türü gönderir. - Custom Header:
X-API-Version: 2gibi özel bir başlık kullanılır.
Avantajları:
- URL'ler temiz kalır; kaynağın URI'si değişmez.
- REST felsefesine daha uygundur çünkü sürüm, kaynağın temsilinin bir parçasıdır.
- İstemciler aynı URI'ye farklı sürüm başlıklarıyla istek yapabilir.
Dezavantajları:
- Keşfedilebilirliği düşüktür; tarayıcıdan test etmek zordur.
- Cache proxy'leri ve bazı ara katmanlar özel başlıkları yok sayabilir.
- İstemcilerin ek başlık gönderme sorumluluğu vardır; unutulması durumunda varsayılan sürüm kullanılır.
Pratik ipucu: Header tabanlı versiyonlama kullanırken hata yönetimi konusunda dikkatli olun. Geçersiz veya eksik sürüm başlığı durumunda 400 Bad Request dönmek yerine varsayılan sürümü (genelde en son kararlı sürüm) kullanmak daha iyi bir kullanıcı deneyimi sağlar. Ayrıca, rate limiting uygularken sürüm bazlı limitler getirmek için bu başlıkları kullanabilirsiniz.
3. Content Negotiation (İçerik Anlaşması) Tabanlı Versiyonlama
Bu yöntemde sürüm, medya türünün bir parçası olarak belirtilir. İstemci Accept: application/json; version=2 veya vendor-specific medya türleri kullanır. Aslında header tabanlı yaklaşımın bir alt kümesidir, ancak REST standartlarına daha yakındır.
Avantajları:
- Tamamen standart HTTP mekanizmasını kullanır.
- Kaynağın URI'si sabit kalır.
- Farklı medya türleriyle esneklik sağlar (örn. XML vs JSON).
Dezavantajları:
- Uygulaması daha karmaşıktır; hem sunucu hem istemci tarafında özel medya türü işleme gerekir.
- Dökümantasyonu zorlaşabilir; her sürüm için farklı medya türleri tanımlanmalıdır.
Kontrol Listesi: Doğru Stratejiyi Seçerken
Aşağıdaki sorularla ihtiyacınıza uygun yöntemi belirleyebilirsiniz:
- Basitlik önceliğiniz mi? → URI tabanlı (hızlıca başlamak için ideal).
- Restful tasarım mı istiyorsunuz? → Content negotiation (en saf REST yaklaşımı).
- Cache ve proxy uyumu önemli mi? → URI tabanlı (header’lar cache’i bozabilir).
- Mobil istemcileriniz mi var? → Header tabanlı (URI değişmediği için güncelleme zahmetsiz).
- Birden çok format (JSON, XML) sunuyor musunuz? → Content negotiation (format ve sürüm aynı anda yönetilir).
Versiyonlama Yaparken Sık Yapılan Hatalar
- Her küçük değişiklikte sürüm yükseltmek: Geriye dönük uyumlu değişiklikler versiyon atlamasını gerektirmez. Sadece kırıcı değişikliklerde (alan adı değişikliği, zorunlu alan ekleme, endpoint silme) yeni sürüm çıkarı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 destekleyin ve kullanıcıları bilgilendirin.
- Versiyon numarasını URL’de taşımak ama header’da da kullanmak: Tek bir yöntem seçin ve tutarlı olun. Karışıklık yaratmayın.
- Versiyonlama yerine “deprecation” başlığı kullanmamak: Eski sürümleri kullanan istemcilere uyarı vermek için
SunsetveyaWarningbaşlıkları ekleyin.
Versiyonlama stratejinizi belirlerken, mevcut API’nizin büyüme hızını, istemci kitlenizi ve ekip tecrübenizi göz önünde bulundurun. Unutmayın: En iyi strateji, ekibinizin uygulamakta en rahat olduğu ve tutarlılıkla sürdürebildiğidir. Daha fazla bilgi için REST API'lerde Veri Doğrulama ve Şema Validasyonu yazımıza da göz atabilirsiniz.
Özet ve Önerilen Aksiyonlar
- Kırıcı değişikliklerde versiyonlama yapın.
- URI tabanlı yöntem başlangıç için en kolayıdır.
- Header tabanlı yöntem, mobil ve uzun soluklu projelerde esneklik sağlar.
- Content negotiation, REST ideallerine en yakın yöntemdir.
- Eski sürümleri planlı şekilde kullanımdan kaldırın.
Sık Sorulan Sorular
REST API'de versiyonlama yapmak zorunda mıyım?
Eğer API'niz uzun süreli kullanılacaksa ve geriye dönük uyumluluğu korumak istiyorsanız versiyonlama şarttır. Küçük iç projelerde geçici olarak versiyonlamadan ilerleyebilirsiniz, ancak yaygın kullanımda kaçınılmazdır.
URI tabanlı versiyonlama mı yoksa header tabanlı mı daha iyi?
URI tabanlı, basitliği ve keşfedilebilirliğiyle öne çıkar; header tabanlı ise REST felsefesine daha uygundur ve URL'leri temiz tutar. Projenizin ihtiyaçlarına göre karar verin: eğer hızlı ve anlaşılır bir çözüm istiyorsanız URI, mobil uyum ve esneklik istiyorsanız header tercih edebilirsiniz.
API versiyonlarını ne zaman kullanımdan kaldırmalıyım?
Eski sürümleri en az 6-12 ay destekleyin ve kullanıcılara geçiş için yeterli süre tanıyın. Kullanımdan kaldırma sürecinde Sunset başlığı ve duyurularla şeffaf olun.
Content negotiation ile versiyonlama nasıl çalışır?
İstemci, Accept başlığına sürümü de içeren özel bir medya türü (örneğin application/vnd.myapi.v2+json) gönderir. Sunucu, bu medya türüne göre ilgili sürümün temsilini döndürür. Bu yöntem, standart HTTP mekanizmasını kullandığı için en restful yaklaşımdır.
