API sürümleme politikası

Moonborn API'si yol-bölümlü sürümleme (path-segment versioning) kullanır: her uç nokta /v1/ (gelecekte /v2/) altında yaşar. Sürüm URL'in parçasıdır; istemciler açıkça sabitler (pin); ana (major) geçişler bilinçli olur, sürpriz değil.

Bu sayfayı bitirdiğinde

• Etkin sürümü (v1) ve yol haritasını bileceksin.
• Hangi değişikliklerin kırıcı (breaking) vs ekleyici (additive) olduğunu ayırt edebileceksin.
• Kullanımdan kaldırma zaman çizelgesini (12 ay geçiş süresi) anlayacaksın.
• SDK'ların API ara (minor) sürümüne nasıl sabitlendiğini öğreneceksin.
• OpenAPI anlık görüntüsünü yeniden üretilebilir derlemeler (reproducible builds) için sabitleyebileceksin.

Ön koşul: Mevcut bir API entegrasyonu.

Etkin sürümler

Kırıcı değişiklik (breaking change) tanımı

Yeni ana sürüm gerektiren değişiklikler:

• Yanıtta bir alanı yeniden adlandırma
• Yanıttan bir alanı kaldırma
• Bir yanıt alanının tipini / şeklini değiştirme
• İsteğe yeni zorunlu alan ekleme
• Bir uç noktayı yeniden adlandırma veya kaldırma
• Uç noktanın kimlik doğrulama gereksinimini değiştirme (örn. yeni yetki zorunlu)
• Zaten kullanımda olan numaralandırma (enum) değerinin anlamını değiştirme

Ekleyici (additive) — sürüm artırımı olmadan iner

Ana sürüm olmadan eklenebilen değişiklikler:

• İsteğe bağlı istek alanları (savunmacı varsayılanlarla)
• Yeni yanıt alanları (istemciler bilinmeyeni görmezden gelir)
• Yeni uç noktalar
• İstek alanlarına yeni numaralandırma değerleri (istemci bildiklerini gönderir; yeni değer kabul edilir)
• Yeni hata kodları (istemci bilinmeyeni varsayılan-ele-almalı)
• Yeni webhook olay tipleri
• Yeni plan-kapısıyla-kontrollü (tier-gated) özellikler (Free istemci mevcut şekli görür; Pro ve üzeri yeni alanları)

Kullanımdan kaldırma zaman çizelgesi

v2 çıktığında:

12 ay geçiş süresi — gelecek ana sürümler için de aynı kural. Güvenlik zorlamaları (örn. acil kullanımdan kaldırma) araya girmediği sürece.

Sürümü çalışma zamanında oku

curl https://api.moonborn.co/v1/version

{
  "apiVersion": "1.2.4",
  "buildSha": "abc123def",
  "deployedAt": "2026-05-17T08:00:00Z"
}

apiVersion semver (anlamsal sürümleme) standardını izler:

• Ana artırım (major bump) (1.x.x → 2.x.x) = yol-sürümü değişikliği (/v1/ → /v2/)
• Ara artırım (minor bump) (1.2.x → 1.3.x) = aynı yol içinde ekleyici değişiklik
• Yama artırımı (patch bump) (1.2.4 → 1.2.5) = hata düzeltmesi, sözleşme değişikliği yok

SDK ↔ API uyumlandırması

Her SDK sürümü bir API ara sürümüne sabitlidir:

SDK yol-sürümü uyuşmazlığında başlamayı reddeder — savunmacı koruma.

OpenAPI belirtimi

/openapi.json her zaman dağıtılmış güncel belirtimi yansıtır:

curl https://api.moonborn.co/openapi.json

Yeniden üretilebilir derlemeler için depoya anlık görüntü sabitle:

curl https://api.moonborn.co/openapi.json > apps/api/openapi-snapshot.json
git add apps/api/openapi-snapshot.json && git commit

CI apps/api/openapi.json ve apps/docs/public/openapi.json'ı bayt-özdeş (byte-identical) tutar — anlık görüntü kayması başarısız olur.

Geçiş deseni — v1 → v2

// Adım 1: Mevcut kodu inceleyip kırıcı değişiklikleri sürüm notlarından listele
// Adım 2: Yeni uç nokta URL'leriyle birlikte SDK yükseltmesi
// Adım 3: Önce hazırlıkta (staging) test et — sandbox `sk_test_*` anahtarı kullan
// Adım 4: Özellik bayrağı (feature flag) arkasında üretimde %5 trafikle başla
// Adım 5: Stabil → %100 geçiş, `v1` kullanan kodu temizle

12 ay geçiş süresi bu adımları sıkıştırmadan yapma olanağı verir. Sonlandırma (sunset) tarihinden 3 ay önce geçişi bitir; son ay üretim-kritik hata düzeltme penceresi olarak kalsın.

Dürüst kapsam

İlgili