Sürümleme ve Uyumluluk
MevzuatRadar herkese açık API sözleşmesinin güncel stabil sürümü /api/v1
altında yayınlanır. OpenAPI çıktısı, SDK kapsamı ve bu dokümantasyon aynı
herkese açık izin listesi üzerine kuruludur.
Stabil Sözleşme
/api/v1 için geriye uyumlu kabul edilen değişiklikler:
- Yeni opsiyonel yanıt alanı eklenmesi.
- Yeni filtre veya sorgu parametresinin opsiyonel olarak eklenmesi.
- Yeni webhook olay değerinin olay kataloğuna eklenmesi.
- Enum kapsamının genişlemesi.
- Hata yanıtına yeni korelasyon veya hata ayıklama alanı eklenmesi.
İstemci tarafı bilinmeyen yanıt alanlarını yok saymalı, bilinmeyen enum veya olay değerlerini kalıcı kuyruğa alıp güvenli yedek davranış ile işlemelidir.
Uyumsuz Değişiklik
Aşağıdaki değişiklikler uyumsuz değişiklik kabul edilir:
- Var olan yol, yöntem veya zorunlu yanıt alanının kaldırılması.
- Alan tipinin değiştirilmesi.
- Zorunlu istek alanı eklenmesi.
- Kimlik doğrulama modelinin daraltılması.
- Webhook imza veya teslimat zarfı sözleşmesinin uyumsuz değişmesi.
Uyumsuz değişiklik gerekiyorsa yeni API versiyonu, geçiş rehberi veya açık kullanımdan kaldırma penceresi hazırlanır. Bu karar değişiklik günlüğü ve müşteri iletişim kanallarıyla duyurulur.
Kullanımdan Kaldırma Süreci
| Aşama | Davranış |
|---|---|
| Duyuru | Değişiklik Günlüğü’nde Deprecation etiketiyle yayınlanır. |
| Paralel çalışma | Eski ve yeni sözleşme birlikte çalışır. |
| Ölçüm | Kullanım telemetry ve müşteri entegrasyon durumu izlenir. |
| Kaldırma | Sözleşmede belirtilen tarihten önce kaldırma yapılmaz. |
OpenAPI ve SDK İlişkisi
OpenAPI çıktısında olmayan endpoint geliştirici dokümantasyonu veya SDK
tarafından canlı herkese açık sözleşme gibi anlatılmaz. SDK metotları
apps/api/openapi.json izin listesiyle uyumlu tutulur; SDK’ya eklenen yeni
metot için önce OpenAPI ve API referansı güncellenir.
Değişiklik Günlüğü İlişkisi
API endpoint, webhook gövdesi, SDK metodu, herkese açık uyumluluk sayfası veya müşterinin görebildiği davranış değişirse Değişiklik Günlüğü kullanılır. İç test, refactor veya CI değişiklikleri herkese açık değişiklik günlüğü girdisi olarak yayınlanmaz.