v1’dir.
URL formatı
Geriye dönük uyumluluk
Bir versiyon içinde aşağıdaki değişiklikler breaking change kabul edilmez ve önceden duyurulmadan yapılabilir:- Yeni opsiyonel alan eklenmesi (request veya response)
- Yeni endpoint eklenmesi
- Yeni opsiyonel header eklenmesi
- Yeni hata kodu eklenmesi
- Yeni webhook olayı eklenmesi
- Yanıt alanlarının sıralamasının değişmesi
- Hata yanıtındaki
titlevedetailmetinlerinde dil/ifade değişiklikleri (kod (code) sabit kalır)
Bilmediğiniz alanları yok sayın.
Bilmediğiniz hata kodlarında HTTP durum kodu kategorisine (4xx / 5xx) göre fallback davranış tanımlayın.
Webhook payload’unda bilmediğiniz
type değerlerini yok sayın, hata fırlatmayın.Breaking change’ler
Aşağıdaki değişiklikler breaking change kabul edilir ve yalnızca yeni bir major versiyonda yapılır:- Mevcut alanın silinmesi veya isminin değişmesi
- Mevcut alanın tipinin değişmesi
- Mevcut endpoint’in URL’sinin değişmesi
- Mevcut zorunlu alanın eklenmesi
- Yanıt yapısının yeniden organize edilmesi
Versiyon yaşam döngüsü
| Aşama | Süre | Açıklama |
|---|---|---|
| Aktif | Süresiz | Yeni özellikler eklenir, üretimde tam destekle çalışır |
| Deprecation | En az 12 ay | Yeni versiyon yayınlandıktan sonra uyarı süresi |
| Sunset | — | Tamamen kapatılır (en az 12 aylık geçişten sonra) |
Deprecation ve Sunset HTTP başlıkları döner:
Yeni versiyon nasıl duyurulur?
Stabil versiyon yayını
Geri bildirim sonrası
v2 stabil sürüm olarak yayına alınır (GA — Generally Available). v1 aktif kalmaya devam eder.Migration rehberi
Tüm breaking change’lerin listesi ve geçiş adımları yayınlanır. Changelog takip edilir.