Uygulamayı aç
Moonborn — Developers

API versioning policy

Moonborn'un API'yi nasıl version'ladığı, deprecation timeline'ları, breaking-change bildirim pencereleri ve neyin breaking change vs additive sayıldığı.

Moonborn'un API'sı path-segment versioning kullanır: her endpoint /v1/ (ya da /v2/ göndereceğimizde) altında yaşar. Version URL'in parçası, client'lar açıkça pin'ler ve migrasyonlar bilinçli olur.

Version'lar

  • v1 — Güncel. General availability. Stabil kontrat'lar.
  • v2 — Henüz çıkmadı. Çıktığında, v1 deprecation penceresine girer (bkz. aşağı).

Neyin breaking change sayıldığı

Yeni version gerektiren değişiklikler:

  • Bir response'daki alanı yeniden adlandırma.
  • Response'tan bir alanı kaldırma.
  • Bir response alanının tipini ya da şeklini değiştirme.
  • Request'e yeni bir zorunlu alan ekleme.
  • Bir endpoint'i yeniden adlandırma ya da kaldırma.
  • Bir endpoint'in auth gereksinimlerini değiştirme (örn. yeni bir scope gerektirme).
  • Zaten kullanımda olan bir enum değerinin anlamını değiştirme.

Additive olan değişiklikler (version bump'sız gönder):

  • Defansif default'ları olan opsiyonel request alanları ekleme.
  • Yeni response alanları ekleme (client'lar bilinmeyen alanları görmezden gelir).
  • Yeni endpoint'ler ekleme.
  • Request alanlarına yeni enum değerleri ekleme (client'lar bildiklerini gönderir; yeni değerler kabul edilir).
  • Yeni error code'ları ekleme (client'lar bilinmeyen code'ları default-handle etmeli).
  • Yeni webhook event tipleri ekleme.
  • Yeni tier-gated feature'lar ekleme (Free client'lar mevcut şekli görür; Pro/Team/Enterprise client'lar yeni alanları görür).

Response alanlarındaki enum eklemeleri teknik olarak breaking — exhaustive pattern-match yapan bir client düşer. Bunları release- notes callout ile dokümante eder ve aşamalı olarak migrate ederiz.

Deprecation timeline

v2 çıktığında:

  • Gün 0: v2 GA. v1 trafiği sunmaya devam eder.
  • Gün 0 + 6 ay: v1 deprecated işaretlenir. Response header'ları Deprecation: true ve Sunset: <tarih> taşır.
  • Gün 0 + 12 ay: v1 kaldırılır. /v1/'a pinli client'lar migration-pointer envelope'lu 410 Gone alır.

Altı ay taban; v1 için özellikle (giriş version'u), deprecation penceresi en az 12 ay olur. Gelecek version bump'lar bir güvenlik zorlama fonksiyonu araya girmedikçe 6 aylık tabanı takip eder.

Version'ı okuma

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

Döner:

{
  "apiVersion": "1.0.0",
  "buildSha": "...",
  "deployedAt": "2026-05-16T08:00:00Z"
}

apiVersion semver'i takip eder. Major bump'lar path-version değişiklikleridir (v1 → v2). Minor + patch bump'lar aynı path içinde kalır.

SDK uyumlanması

Her SDK release'i bir API minor version'una pin'lidir. SDK 1.4.x API 1.4.*'ı konuşur; SDK 2.0.x API 2.x'i konuşur. SDK path-version uyuşmazlığına karşı başlamayı reddeder.

OpenAPI spec'i

/openapi.json her zaman güncel deployed spec'i yansıtır. Kendi client'larını bundan kur; reproducible build'ler istersen repo'nda bir snapshot pin'le. CI apps/api/openapi.json ve apps/docs/public/openapi.json'ı byte-identical tutar.

Dürüst kapsam

Birden fazla minor version'ı eş zamanlı sürdürmüyoruz. v1.4 çıktıysa v1.3'ü istemenin yolu yok — minor bump'lar sadece additive, yani v1.3 ve v1.4 client POV'unda wire-uyumlu.

Major version sözleşme birimi. v1'e pin'le; deprecation penceresi açıldığında migrate et; öncesinde değil.

Sonraki