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ü
Deprecation döneminde ilgili endpoint’ler
Deprecation ve Sunset HTTP başlıkları döner:
Yeni versiyon nasıl duyurulur?
1
Beta yayını
Yeni versiyon
v2-beta olarak duyurulur, yorum/feedback toplanır.2
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.3
Migration rehberi
Tüm breaking change’lerin listesi ve geçiş adımları yayınlanır. Changelog takip edilir.
4
Deprecation süreci
v1 deprecation süresine alınır (minimum 12 ay).