API Versiyonlama Stratejileri: URL, Header ve Query Parametre Yöntemleri

API versiyonlama, bir API'nin farklı sürümlerini yönetmek ve tüketicilere kesintisiz hizmet sağlamak için kullanılan bir yaklaşımdır. Yanlış versiyonlama stratejisi, mevcut istemcilerin bozulmasına, bakım zorluklarına ve geliştirici deneyiminin düşmesine yol açar. Peki, en yaygın üç yöntem olan URL path, custom header ve query parametre tabanlı versiyonlama nasıl çalışır? Hangi durumda hangisi tercih edilmelidir? Bu yazıda her bir yöntemin avantajlarını, dezavantajlarını ve pratik kullanım senaryolarını detaylıca ele alıyoruz.

Neden API Versiyonlama Gereklidir?

Bir API zaman içinde değişir: yeni alanlar eklenir, eski alanlar kaldırılır, davranışlar iyileştirilir. Eğer bu değişiklikler geriye uyumlu değilse, mevcut istemciler (mobil uygulamalar, üçüncü parti entegrasyonlar) hata almaya başlar. API versiyonlama, bu sorunu çözmek için farklı sürümlerin aynı anda çalışmasına izin verir. REST API Hata Yönetimi yazımızda da değindiğimiz gibi, uygun HTTP durum kodları kullanmak kadar versiyonlama da API güvenilirliğinin temel taşlarındandır.

URL Path Tabanlı Versiyonlama

En yaygın kullanılan yöntemdir. API endpoint'lerinin başına sürüm numarası eklenir: /api/v1/users, /api/v2/users. Bu yöntem oldukça basit ve anlaşılırdır. Geliştiriciler hangi sürümü kullandıklarını URL'den hemen görebilir. Örneğin, bir mobil uygulama v1'i kullanırken web uygulaması v2'yi kullanabilir.

Avantajları: Kolay uygulanabilir, URL'den sürüm belli olduğu için hata ayıklaması basittir. HTTP önbellekleme (cache) açısından da temizdir, çünkü farklı URL'ler farklı kaynak olarak algılanır.

Dezavantajları: URL'de sürüm numarası taşıması, REST prensiplerine göre kaynağın URI'sinin değişmez olması gerektiği görüşüyle çelişir. Ayrıca her sürüm için ayrı bir routing (yönlendirme) ve kod tabanı yönetimi gerekebilir. Zamanla URL'lerin şişmesine yol açar.

Custom Header ile Versiyonlama

İsteğe özel bir header eklenerek sürüm belirtilir: Accept: application/vnd.bizimblog.v2+json veya X-API-Version: 2. Bu yöntem, URL'yi temiz tutar ve kaynağın URI'sini sabit bırakır.

Avantajları: RESTful prensiplere daha uygundur; kaynak URI'si değişmez. İstemciler aynı URL'yi kullanır, ancak header ile farklı sürümleri talep eder. Bu sayede HTTP önbellekleme daha etkili olabilir (farklı header değerleri farklı varyantlar olarak işlenebilir).

Dezavantajları: Header'lar URL kadar görünür değildir, bu nedenle hata ayıklama ve test etme biraz daha zordur. Tarayıcı gibi araçlarla doğrudan erişimde header eklemek kullanıcı dostu olmayabilir. Ayrıca API dokümantasyonunda header değerlerinin açıkça belirtilmesi gerekir.

Query Parametre ile Versiyonlama

Sürüm bilgisi URL'ye parametre olarak eklenir: /api/users?version=2. Bu yöntem, header yöntemine benzer şekilde URL'yi değiştirmeden versiyonlamaya izin verir, ancak query string kullanır.

Avantajları: Uygulaması basittir, çoğu framework query parametreleri kolayca işler. Tarayıcıdan doğrudan erişimde parametre eklemek kolaydır.

Dezavantajları: Query parametreleri, URL'nin bir parçası olduğu için HTTP önbellekleme açısından URL path yöntemi kadar temiz değildir. Aynı kaynak için farklı sorgu parametreleri farklı önbellek anahtarları oluşturur, ancak bu bazen istenmeyen durumlara yol açabilir. Ayrıca, standart dışı olarak kabul edilebilir; REST puristleri tarafından pek tercih edilmez.

Karşılaştırma Tablosu

Sık Yapılan Hatalar ve Dikkat Edilmesi Gerekenler

• Sürüm numarasını sabit kodlamak: İstemcilerde sürümü sabit kodlamak yerine, API'den sürüm bilgisi almak için bir endpoint sağlamak daha esnektir.
• Aşırı versiyonlama: Her küçük değişiklikte yeni sürüm çıkarmak yönetilebilirliği azaltır. Geriye uyumlu değişiklikler için sürüm yükseltmek gerekmez.
• Deprecation (kullanımdan kaldırma) sürecini atlamak: Eski sürümleri aniden kapatmak yerine, istemcilere geçiş süresi tanımak için Deprecation ve Sunset header'ları kullanılabilir. Bu konuda API Caching Best Practices yazımızdaki “deprecation” bölümüne de göz atabilirsiniz.

Hangi Stratejiyi Seçmelisiniz?

Seçim, projenizin ihtiyaçlarına ve ekibin alışkanlıklarına bağlıdır. Eğer API'niz geniş bir kitleye hitap ediyor ve kolay keşfedilebilirlik ön plandaysa URL path iyi bir seçenektir. REST prensiplerine sıkı sıkıya bağlıysanız ve istemcilerin çoğu programatik olarak erişiyorsa custom header daha uygundur. Hızlı prototipleme ve basit projelerde query parametre kullanılabilir, ancak uzun vadede yönetimi zorlaşabilir. Unutmayın: hangi yöntemi seçerseniz seçin, dokümantasyonu güncel tutmak ve geçiş süreçlerini iyi planlamak API'nizin başarısı için kritik öneme sahiptir.

Sık Sorulan Sorular

API versiyonlamada hangi yöntem en yaygındır?

URL path tabanlı versiyonlama (ör. /api/v1/users) en yaygın kullanılan yöntemdir. Basit ve anlaşılır olması sayesinde geliştiriciler tarafından sıkça tercih edilir.

Custom header ile versiyonlama neden tercih edilir?

Custom header yöntemi, REST prensiplerine daha uygundur çünkü kaynağın URI'sini değiştirmez. Aynı URL ile farklı sürümlerin talep edilmesine olanak tanır ve HTTP önbellekleme açısından da avantaj sağlayabilir.

Query parametre ile versiyonlama güvenilir midir?

Evet, güvenilir bir yöntemdir ancak HTTP önbellekleme açısından URL path kadar temiz değildir. Basit projelerde veya geçici çözümlerde kullanılabilir.

API versiyonlarken sık yapılan hatalar nelerdir?

En sık yapılan hatalar: sürüm numarasını istemci tarafında sabit kodlamak, her küçük değişiklikte yeni sürüm çıkarmak ve eski sürümleri aniden kapatarak deprecation sürecini atlamaktır.