Stripe API versiyonlama: nasıl çalışır, neler kopyalanır

Stripe API versiyonlama tarihe göre çalışır. Her hesap, bir yayın tarihinden adını alan bir API sürümüne sabitlenir ve tek tek her istek bu sabitlemeyi bir Stripe-Version header’ıyla ezebilir. Bu yazı sırasında (Ekim 2026), Stripe dokümanlarındaki güncel sürüm 2026-09-30.endive ve aynı şemayı çok daha küçük bir API bir hafta sonunda kopyalayabilir.

Aşağıdaki her Stripe olgusu Stripe’ın kendi sayfalarından gelir ve kullanıldığı yerde bağlantılıdır.

Stripe API versiyonlama nasıl çalışır?

Stripe her hesaba varsayılan bir API sürümü verir ve bir sürüm adlandırmayan her istek onu kullanır. Çağıranlar ne zaman geçeceklerini, varsayılanı değiştirerek ya da tek tek isteklerde bir sürüm ayarlayarak seçer.

Stripe’ın mühendislik yazısına göre hesap, ilk API isteğini yaptığında sabitlenir: hesap “automatically pinned to the most recent version available” olur ve o andan sonra her çağrıya bu sürüm örtük olarak atanır.

Sürüm dizesi bir tarihtir. 2024-09-30.acacia release’inden beri bir ad da taşır, 2026-09-30.endive örneğindeki gibi. Tarih sürümleri sıralar, ad ise bir sürümün hangi major release ailesine ait olduğunu söyler.

İstek başına sürüm nasıl seçilir?

İstekte Stripe-Version header’ını gönderin ya da sürümü SDK’da ayarlayın. Stripe’ın yükseltme rehberi header biçimini gösterir ve aynı çağrı canlı ve test ortamlarında çalışır.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

Stripe’ın rehberi, sürümü bir SDK’da global olarak ya da istek başına ayarladığınızda yanıt nesnelerinin o sürümde döndüğünü not eder.

Stripe ayrıca hesap varsayılanına yaslanmamayı önerir. Kendi sözleriyle, kodunuz sürüme karar versin ve bir panel ayarı vermesin diye, her istek için header ile ya da sabitlenmiş bir SDK ile sürümü belirtin.

SDK’lar dile göre farklı sabitlenir. Dokümanlar, dinamik tipli kütüphanelerin son sürümlerinin o SDK release’i yayımlandığında en güncel olan API sürümünü kullandığını, güçlü tipli olanların (Java, Go ve .NET) ise ona sabitlendiğini söyler. Bir kütüphane sürümünü kurmak, fiilen bir API sürümü seçmektir.

Sürüm değiştiğinde webhook’lara ne olur?

Bir webhook olayı, sunucu kodunuzun kullandığı sürümde değil, endpoint’ine bağlı API sürümünde işlenir. Stripe’ın dokümanları, olayların endpoint oluşturulurken ayarlanan sürümü, yoksa hesap varsayılanını kullandığını söyler. SDK sürümünüzü değiştirmek webhook handler’ınızın aldığını değiştirmez.

Bu yüzden istek yolunuz ve olay yolunuz iki farklı sürümde durabilir. Olay hedefleri için snapshot_api_version’ı sadece hedefi oluştururken ayarlarsınız, yani farklı bir sürüm yeni bir hedef demektir.

Stripe’ın buradaki yükseltme yolu paralel bir çalıştırmadır. Hedef sürümde yeni bir endpoint oluşturun, aynı olayları ikisine de gönderin, handler’a birini işlemeyi ve diğerini yok saymayı öğretin, sonra geçin ve eski endpoint’i devre dışı bırakın. Çakışma süresince her olay iki kez geldiği için handler idempotent olmalıdır. Bu, olay yayan her API için kopyalanacak iyi bir kalıptır ve gerektiren payload değişikliklerini duyurduğunuz yer bir webhook changelog’u olur.

Aylık ve major release’ler nedir?

2024-09-30.acacia release’inden beri Stripe aylık olarak breaking change içermeyen yeni bir API sürümü yayımlar ve yılda iki kez, breaking change içeren bir sürümle başlayan yeni bir major release çıkarır. Versioning sayfası, herhangi bir aylık release’e kodunuzu güncellemeden yükseltebileceğinizi, bir major release’in ise değişiklik gerektirebileceğini söyler.

Major release’ler ad taşır. Versioning sayfası örnek olarak Basil’i verir ve Stripe’ın süreç duyurusu, adların bitkilerden geldiğini, Acacia ile başladığını ve aylık release’lerin kendilerinden önceki major release’in adını koruduğunu, böylece adın yükseltmenin güvenli olduğunu işaret ettiğini söyler. Stripe’ın changelog’u kullanımdaki adları listeler ve bu yazı sırasında en yeni girdi 2026-09-30.endive’dir.

Yani tarih “ne kadar yeni” sorusunu, ad ise “bu bir breaking sınırı mı” sorusunu cevaplar. Stripe’ın duyurusu istisnalara da yer bırakır: bir entegrasyonun onsuz ciddi biçimde etkileneceği yerde döngü dışı bir breaking change yayımlama hakkını saklı tutar. Duyuru Stripe’s new API release process adresinde.

Stripe API’nin son sürümü nedir?

Bu yazı sırasında (Ekim 2026), Stripe’ın versioning sayfası güncel sürümün 2026-09-30.endive olduğunu söyler ve changelog’u aynı sürümü en yeni olarak listeler. Stripe her ay yeni bir sürüm yayımlar, bu yüzden bir makalede basılı her dize hızla eskir. Bir şeyi sabitlemeden önce canlı changelog’u okuyun ve test ettiğiniz sürümü sabitleyin.

Stripe eski sürümleri nasıl çalışır tutuyor?

Stripe, her breaking change’i kendi içinde tamamlanmış bir sürüm değişikliği modülü olarak yazarak ve modülleri verinin en yeni biçiminden geriye doğru uygulayarak eski sürümleri canlı tutar. API versiyonlama üzerine mühendislik yazısı mekanizmayı anlatır.

Her modül neyi değiştirdiğini bildirir, değişikliği belgelendirir ve bir dönüşüm fonksiyonu içerir. Yazı, bir alanın string’den hash’e değişmesi örneğini verir. Bir yanıt oluşturmak için sistem hedef sürümü bulur, sonra zamanda geriye yürür ve o sürüme varana kadar yol boyunca bulduğu her modülü uygular.

Bu tasarımdan iki yan etki doğar ve yazı ikisini de adlandırır. Modüller dokunduğu alanları ve kaynakları bildirdiği için Stripe, API changelog’unu dağıtım sırasında onlardan üretebilir. Hesabın sürümü bilindiği için de dokümantasyon ona uyum sağlayabilir ve o sürümden beri geriye uyumsuz değişiklikler hakkında uyarabilir.

Maliyeti nedir ve küçük bir API ne kopyalamalı?

Versiyonlama mühendislik dikkati maliyeti taşır ve Stripe bunu söyler. Mühendislik yazısı bir bakım yükünü kabul eder ve yeni kod yazarken eski davranış için ne kadar az düşünmek gerekirse o kadar iyi olduğu hedefini belirtir. Ayrıca hiç sürüm değişikliği gerektirmemek için release öncesi hafif API incelemelerini de anlatır.

Küçük bir API her eski sürüm için bir modül zincirini karşılayamaz ve buna ihtiyacı da yoktur. Değeri taşıyan parçaları kopyalayın:

1. Tarihli sürümler. Bir tarih, neyin “major” sayıldığına dair yargı gerektirmez ve çağıranlar onu okuyabilir. Versiyonlama en iyi uygulamaları makalesi bunu URL ve header şemalarıyla karşılaştırır.
2. Sabitlenmiş bir varsayılan. Hesabı ya da anahtarı ilk kullanımda sürüme sabitleyin, böylece API çalışan bir entegrasyonun altından kaymaz.
3. İstek başına bir ezme. Çağıranın yeni bir sürümü, taahhüt etmeden önce tek bir çağrıda, canlıda test etmesini sağlayan bir header.
4. Webhook endpoint’inde bir sürüm. Olay payload’ları, çağıranların en çok şaşırdığı yerdir.
5. Sürüm başına bir changelog girdisi. Sürümü, tarihi, kimin etkilendiğini ve ne yapılacağını adlandırsın. Neyin breaking sayıldığı, yeni bir sürüme neyin ait olduğunun testidir ve API changelog makalesi girdinin kendisini ele alır.

Desteklenen sürüm sayısı sizi zorlayana kadar modül zincirini atlayın. İki ya da üç canlı sürüm birkaç dal ve bir sunset tarihiyle idare edilebilir; bunu bir API sürümünü kapatmak yazısı adım adım anlatır.

Tarihli bir changelog yayımlıyorsanız, sürüm geçmişi girdileri kadar iyidir. Changeloop’ta her merge edilen pull request’ten bir girdi taslağı hazırlanır ve changelog sayfasına ve feed’e yayımlanmadan önce bir insanın onaylaması için bekletilir. Sürüm başına girdi orada yazılır ve tek insan kapısı, çağıranın ne yapması gerektiğini söyleyen gözden geçirmedir.

FAQ

Stripe API’nin son sürümü nedir? Bu yazı sırasında (Ekim 2026), Stripe’ın versioning sayfası güncel sürümün 2026-09-30.endive olduğunu söyler. Stripe her ay yeni bir sürüm çıkarır, bu yüzden sabitlemeden önce changelog’una bakın ve hesap varsayılanına yaslanmak yerine sürümü kodunuza yazın.

Bir istekte Stripe API sürümünü nasıl ayarlarım? Stripe-Version header’ını gönderin, örneğin Stripe-Version: 2026-09-30.endive, ya da sunucu tarafı SDK’nızda sürümü global olarak veya istek başına ayarlayın. İkisi de yoksa istek, Workbench’te sizin ayarladığınız hesabınızın varsayılan sürümünü kullanır.

Webhook’lar isteklerimle aynı Stripe API sürümünü kullanır mı? Mutlaka değil. Webhook olayları endpoint oluşturulurken ayarlanan sürümü, hiçbiri ayarlanmadıysa hesap varsayılanını kullanır. SDK’nızı yükseltmek webhook handler’ınızın aldığı payload’ı değiştirmez, bu yüzden endpoint’leri ayrı yükseltin ve paralel test edin.

Stripe tarzı tarihli versiyonlama küçük bir API için doğru mu? Tarihli sürümler, sabitlenmiş bir varsayılan, istek başına bir header ve sürüm başına bir changelog girdisi ucuzdur ve kopyalamaya değer. Aynı anda birçok eski sürümü desteklemediğiniz sürece, sürüm değişikliği modüllerinin iç zinciri öyle değildir. İki canlı sürümle ve eskisi için bir sunset tarihiyle başlayın.

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