REST API versiyonlama: URL, başlık ya da sorgu, hangisi uyar

REST API versiyonlama, bir API’nin çağırana bir isteğin hangi sözleşmeyi kullandığını söyleme yoludur; böylece sunucu, henüz taşınmamış çağıranları bozmadan sözleşmeyi değiştirebilir. Versiyonun gidebileceği üç yer vardır: URL yolu (/v2/orders), bir istek başlığı (Accept: application/vnd.acme.v2+json ya da özel bir Api-Version: 2026-10-01) ya da bir sorgu parametresi (/orders?version=2). Yol en yaygın olanıdır çünkü her yerde görünür, başlık URL için en temiz olanıdır, sorgu dizesi ise çoğu ekibin pişman olduğu seçenektir. Hangisinin uyduğu, çağıranlarınızın kim olduğuna ve değişiklikleri onlara nasıl duyurmayı planladığınıza bağlıdır.

Bir REST API’sinde v1 ve v2 nedir?

v1 ve v2, API sözleşmesinin iki versiyonunun etiketleridir: aynı kaynaklar, farklı yollardan erişilebilir; v2 alanları yeniden adlandırabilir, türleri değiştirebilir, endpoint’leri kaldırabilir ya da v1 çağıranlarının güvendiği hata şekillerini değiştirebilir. /v1/orders’a yapılan bir istek, v1 desteklendiği sürece eski şekli almaya devam eder; /v2/orders’a yapılan bir istek yenisini alır. Numara uyumluluk hakkında bir sözdür ve onu kullanışlı yapan bu sözdür. Her release’te artırmak etiketi gürültüye çevirir.

Çoğu API’nin yeni bir major versiyona yalnızca mevcut çağıranları bozan bir değişiklik için ihtiyacı olur. Bir alan, yeni bir endpoint ya da yeni bir isteğe bağlı parametre eklemek mevcut versiyon altında gönderilebilir, çünkü iyi yazılmış bir istemci bilmediğini yok sayar. Bir API ne zaman versiyonlanmalı ve yerine ne yapılmalı kararı ele alır; bu makale, artırmaya karar verdikten sonra REST API versiyonlamada versiyonun nereye gideceği hakkındadır.

REST API versiyonlama URL’ye mi yoksa başlığa mı konmalı?

Çağıranlarınız arasında tarayıcıya istek yazan, dokümantasyondan örnek kopyalayan ya da log okuyan insanlar varsa URL’ye koyun; kaynak başına tek bir kararlı URL istiyorsanız ve çağıranlarınızın hepsi SDK’lar ya da kontrol ettiğiniz kodsa başlığa koyun. URL yolu başka hiçbir şeyin olmadığı kadar açıktır: içinde istek satırı olan bir destek bileti versiyonu zaten söyler. Bir başlığın her istekte ayarlanması gerekir, bir bağlantıda görünmez ve bir proxy’de kolayca kaybolur; başlıkla versiyonlanan API’lerin göndermeyen istekler için her zaman bir varsayılan tanımlamasının nedeni budur.

Başlık yaklaşımının düzenli URL’lerin ötesinde gerçek bir avantajı vardır: kaynağın kimliğini temsilinden ayırır, HTTP böyle tasarlanmıştır. RFC 9110, Accept üzerinden içerik müzakeresini anlatır ve application/vnd.github.v3+json gibi bir medya türü, bu yolla ifade edilmiş bir versiyondur. Pratikte tasarım saflığı, çağıranlarınızın başlığı göndermeyi hatırlayıp hatırlamadığından daha az önemlidir.

Tarih tabanlı versiyonlama nasıl çalışır?

v1 ve v2 yerine versiyon bir tarihtir ve her breaking change yeni bir tarih alır. Çağıran, entegre olduğu tarihi, genellikle hesap düzeyinde bir kez sabitler ve taşınmayı seçene kadar o davranışı korur. Stripe’ın Stripe-Version başlığı ve GitHub’ın X-GitHub-Api-Version başlığı bu şekilde çalışır.

Ödün uygulamadadır. Her breaking change, sabitlenen tarih ile güncel şekil arasında çeviri yapan küçük bir dönüşüm katmanı olur ve sunucu bunları üst üste yığar: iki yıl geriye sabitlenmiş bir istek o zamandan beri her değişiklikten geçer. Bu, handler’ların ikinci bir kopyasından daha ağır bir inşadır ve nadiren değişen bir API’yi ödüllendirir. Ayda bir breaking change gönderen ekipler düzinelerce dönüşümle kalır. Stripe API versiyonlama modele çağıranın tarafından bakar, changelog’un ne taşıması gerektiği dahil.

Sorgu dizesiyle versiyonlama neden önerilmez?

Çünkü sözleşmeyi filtrelerle karıştırır. /orders?status=open&api-version=2, versiyonu yanıttaki her alanın şeklini belirleyen şey yerine isteğe bağlı bir ince ayar gibi gösterir. Ayrıca kazara düşürülmesi en kolay olanıdır, çünkü sorgu dizeleri istemci kütüphanelerince yeniden kurulur, bazı proxy’lerce soyulur ve insanlarca elle düzenlenir. Microsoft’un kendi REST API tasarım kılavuzu Azure’un kullandığı sorgu parametresi biçimini belgeler ve bunu işler kılan, etrafındaki üretilmiş SDK ekosistemidir; o araçlar olmadan parametreyi unutan bir çağıran sessizce varsayılan versiyonu alır.

Eski versiyona ne olur?

Çalışmaya devam eder, durduğu bir tarihle. Versiyonlamanın amacı çağıranların kendi takvimlerine göre taşınmasına izin vermektir ve bu yalnızca eski versiyon bunu yapmalarına yetecek kadar uzun süre erişilebilir kalırsa ve ne zaman biteceği onlara söylenirse doğrudur. Google’ın API versiyonlama kılavuzu kendi API’leri için kullandığı yaşam döngüsünü anlatır: kararlı bir versiyon yayımlanmış bir deprecation tarihine kadar desteklenir, yerine geçecek olan bütün deprecation penceresi boyunca erişilebilirdir.

Duyuru, çoğu ekibin eksik kurduğu kısımdır. Yeni bir yol ya da başlık yalnızca var olduğunu, neyin değiştiğini ve v1’in ne zaman gideceğini bilen çağıranlar için işe yarar. Bu üç olgudur ve her birinin bir yuvası olmalı: alan düzeyindeki farklarla API changelog’da tarihli bir girdi, bitiş tarihini belirten bir deprecation bildirimi ve hâlâ eski versiyonda olan bir çağıran için her değişikliği adım adım anlatan bir geçiş kılavuzu. Bir API versiyonunu kapatmak son adımı ele alır; istemcinin tarihi her yanıtta keşfetmesini sağlayan Sunset başlığı dahil.

REST API versiyonlamadan tamamen kaçınılabilir mi?

Evet, her değişiklik ekleme olduğu sürece. Alan ekleyin, asla kaldırmayın ya da yeniden adlandırmayın; endpoint ekleyin, mevcut birinin döndürdüğünü asla değiştirmeyin; yeni isteğe bağlı parametreler kabul edin, eskisinin anlamını asla değiştirmeyin. Birçok dahili API yıllarca yalnızca bu kuralla çalışır ve GraphQL şemalarının tasarım gereği izlediği kural budur. Bedeli, yalnızca büyüyen bir sözleşmedir; biri, bir yerde hâlâ okuduğu için kalması gereken deprecate edilmiş alanlarla.

Ekleme bir değişiklik imkansız olduğunda araç versiyondur. Yol, başlık ve tarih arasındaki seçim çağıranların ne gördüğünü ve değişikliğin nasıl duyurulduğunu belirler; sabit kalan, değişikliğin çağıranın okuyacağı bir yere yazılması gerektiğidir. Dış çağıranları olan bir API için o yer changelog’dur ve breaking change’ler yazısı neyin sayıldığını anlatır.

FAQ

Bir REST API’yi versiyonlamanın en iyi yolu nedir? URL yolundaki bir major versiyon en yaygın anlaşılan ve yanlış yapılması en zor olandır, bu yüzden genel bir API için varsayılandır. Bir başlık versiyonu URL’leri kararlı tutar ve SDK odaklı API’lere uyar; tarih tabanlı bir başlık nadiren değişen ve çağıranların davranışı sabitlemesini isteyen API’lere uyar.

Bir API URL’sindeki v1 nedir? API sözleşmesinin ilk major versiyonudur. /v1/...’e yapılan isteklere, farklı alanları ya da davranışı olan bir /v2/ var olduktan sonra bile, versiyon 1 için belgelenmiş şekil vaat edilir.

Her değişiklik için yeni bir API versiyonuna ihtiyacım var mı? Hayır. Yeni alanlar, endpoint’ler ve isteğe bağlı parametreler gibi ekleme değişiklikleri mevcut versiyon altında gönderilebilir. Yalnızca mevcut çağıranları bozan bir değişiklik yenisine ihtiyaç duyar.

Eski bir API versiyonu ne kadar süre desteklenmeli? Çağıranların geçiş yapmasına yetecek kadar; genel bir API için bu genellikle yerine geçenin erişilebilir olmasından sonra altı ila on iki aydır, tarih duyuruda yayımlanır ve deprecation bildiriminde yinelenir.

Bu yazıdaki teknik iddialar bağımsız olarak kontrol edilmedi. Yanlış bir şey varsa bize söyle, düzeltelim.

changeloop'ta ilgili sayfalar: Geliştirici dokümantasyonu, Changelog örnekleri