Ana içeriğe geç
Software Dictionary
Kitap 03 · Backend ve API'lerSayfa 4 / 48

API Versioning

Türkçe karşılığı
API sürümleme, API versiyonlama
Okunuşu
ey-pi-ay vörjıning

Günlük kullanımda iki ad da yaygın.

Güncellendi 2 dk okuma

Bu sayfayı paylaşın

Bağlantıyı gönderin, tanımı bağlantısıyla birlikte alıntılayın ya da kendi sitenizde bir kart olarak gösterin.

https://softwaredictionary.org/tr/terimler/api-versioning

Kısaca

API versioning, bir API'deki değişiklikleri etiketleyip yönetmektir; mevcut istemciler çalışmaya devam ederken yeni sürümler özellik ekler veya değiştirir.

API versioning nedir?

API versioning, bir API'yi kendisine zaten bağımlı olan uygulamaları bozmadan geliştirmenin yoludur. Diğer geliştiriciler API'nize göre kod yazdıktan sonra bir yanıt alanını yeniden adlandırmak veya bir endpoint'i kaldırmak onların kodunu bozabilir; bu yüzden geriye dönük uyumsuz değişiklikleri v2 gibi yeni bir sürüm altında yayımlar ve eski sürümü bir süre çalışır durumda tutarsınız.

Bir istemcinin hangi sürümü istediğini belirtmesinin birkaç yaygın yolu vardır. URL yolu ile sürümleme, sürümü /v1/users gibi yolun içine koyar; bu en görünür yaklaşımdır ve test etmesi en kolay olanıdır. Header ile sürümleme özel bir başlık ya da Accept başlığını kullanır, sorgu parametresiyle sürümleme ise ?version=2 gibi bir şey kullanır. Bazı API'ler sayı yerine 2026-09-30 gibi yayın tarihleri kullanır; böylece her istemci belirli bir sürümün davranışına sabitlenir.

Sürümleri bir ders kitabının baskılarına benzetin: ikinci baskıyı kullanan bir okul, üçüncü baskı bölümlerin sırasını değiştirse bile geçişe hazır olana kadar ondan ders vermeye devam edebilir. Sürümleme en çok herkese açık API'lerde, kullanıcıların hemen güncellemediği mobil uygulamalarda ve tüm istemcileri aynı anda güncelleyemeyeceğiniz iş ortağı entegrasyonlarında önem kazanır.

API versioning sıklıkla yazılım paketlerinin anlamsal sürümlemesiyle (semantic versioning) karıştırılır. Anlamsal sürümleme, geriye dönük uyumsuz değişiklikleri, yeni özellikleri ve düzeltmeleri belirtmek için 2.4.1 gibi üç sayı kullanır; herkese açık API'ler ise genellikle yalnızca ana sürümü gösterir, çünkü yalnızca uyumsuz değişiklikler istemcilerin harekete geçmesini gerektirir. İsteğe bağlı alan veya yeni endpoint eklemek geriye dönük uyumludur ve yeni sürüm gerektirmez; ancak alanları kaldırmak, yeniden adlandırmak veya tiplerini değiştirmek gerektirir. Eski sürümler de örneğin Deprecation ve Sunset yanıt başlıklarıyla önceden haber verilerek kullanımdan kaldırılmalıdır.

Önemli noktalar

  • Sürümleme, bir API'nin mevcut istemcileri bozmadan uyumsuz değişiklikler yapmasını sağlar.
  • Yaygın yaklaşımlar sürümü URL yoluna, bir başlığa ya da bir sorgu parametresine koyar.
  • İsteğe bağlı alan eklemek geriye dönük uyumludur; alanları kaldırmak veya yeniden adlandırmak uyumsuz bir değişikliktir.
  • Herkese açık API'ler genellikle yalnızca v1 veya v2 gibi bir ana sürüm gösterir.
  • Eski sürümleri net takvimlerle ve Sunset gibi başlıklarla kullanımdan kaldırın.

Örnek

curl ile belirli API sürümlerini istemekbash
# URL path versioning: the version is part of the address
curl https://api.example.com/v1/users/42
curl https://api.example.com/v2/users/42

# Header versioning: same URL, version sent in a header
curl https://api.example.com/users/42 \
  -H "Accept: application/vnd.example.v2+json"

# Query parameter versioning
curl "https://api.example.com/users/42?version=2"

# Date-based versioning: pin the client to a release date
curl https://api.example.com/users/42 -H "Api-Version: 2026-09-30"

Sık sorulan sorular

Bir API'yi sürümlemenin en iyi yolu nedir?

Tek bir en iyi yol yoktur, ancak /v1/ gibi URL yolu ile sürümleme; basit, görünür, önbelleğe alması ve test etmesi kolay olduğu için en yaygın olanıdır. Header tabanlı sürümleme URL'leri temiz tutar ancak tarayıcıda denemesi daha zordur.

Yeni bir API sürümünü ne zaman oluşturmalıyım?

Yalnızca alanları kaldırmak veya yeniden adlandırmak, veri tiplerini değiştirmek ya da zorunlu parametre eklemek gibi geriye dönük uyumsuz değişiklikler için oluşturun. Yeni isteğe bağlı alanlar ya da yeni endpoint'ler gibi geriye dönük uyumlu değişiklikler mevcut sürümde yayımlanabilir.

Eski API sürümleri ne kadar süre desteklenmelidir?

Kullanıcılarınıza bağlıdır, ancak herkese açık API'ler bir sürümü kaldırmadan önce yaygın olarak en az 6 ile 12 ay önceden haber verir. Takvimi duyurun, kullanımdan kaldırma başlıkları gönderin ve hangi istemcilerin hâlâ eski sürümü kullandığını izleyin.

İlgili sayfalar

Bu sayfada bir hata ya da eksik mi gördünüz?Düzeltme önerin

Daha fazla

Ayarlar

EnglishTürkçe