Sürümleme ve Uyumluluk
Müşteri API’si ve herkese açık arşiv yolları /api/v1 önekiyle tanımlıdır.
Örneğin /api/v1/changes ve /api/v1/public/regulations bu sürümü kullanır.
Sağlık kontrolü /health altında, OpenAPI ise etkinleştirildiğinde
/api/docs ve /api/docs-json yollarındadır; bu yollara /api/v1 eklenmez.
Yol ve Belge Sürümü
| Değer | Anlam |
|---|---|
v1 | API yollarında kullanılan ana sürüm |
1.0.0 | OpenAPI belgesindeki info.version değeri |
Belge sürümü dağıtılan Git SHA’sı değildir. Çalışan API’nin kod kimliği
Sağlık Kontrolü yanıtındaki sourceCommit ile izlenir.
Yollar controller tanımlarında açıkça yazılır. Bir istemci Accept başlığına
sürüm ekleyerek belgelenmemiş başka bir API sürümünü seçemez.
Uyumlulukta İstemci Davranışı
İstemciler yeni yanıt alanlarına toleranslı olmalı; opsiyonel veya null
alanları işlemelidir. Yeni enum değerleri ve Webhook olayları istemci iş
mantığını etkileyebileceğinden, bunların her durumda geriye uyumlu olduğu
varsayılmaz. Bilinmeyen değerler için açık bir yedek davranış gerekir.
Yolun, yöntemin, zorunlu alanın veya alan tipinin değişmesi; yeni zorunlu istek alanı eklenmesi ve kimlik doğrulama koşullarının değişmesi entegrasyon üzerindeki etkisiyle değerlendirilir. Yeni filtre yalnız o endpointin sözleşmesinde varsa gönderilir; bilinmeyen DTO alanları reddedilir.
Kullanımdan Kaldırma Politikası
Bir yol, alan veya Webhook olayı kaldırılacaksa kaldırma tarihi duyurudan en az altı takvim ayı sonradır. Duyuru iki kanaldan yapılır:
| Kanal | Kapsam |
|---|---|
| Değişiklik Günlüğü | Kaldırılan öğe, ardılı ve kaldırma tarihi |
| E-posta | Aşağıdaki alıcılara mevcut e-posta altyapısıyla bildirim |
E-posta alıcıları kayıtlı bağlardan bulunur:
- süresi dolmamış, etkin API anahtarlarını oluşturan ve hâlâ o kurumun etkin üyesi olan kullanıcılar,
- açık durumdaki entegrasyon uygulamalarının bağlı geliştirici hesabı iletişim adresi,
- aynı hesap, uygulamanın açık bir Webhook ucu varsa uç sahibi olarak,
- kurum düzeyindeki açık Webhook uçlarını oluşturan ve hâlâ o kurumun etkin üyesi olan kullanıcılar (oluşturma denetim kaydından).
İptal edilmiş veya süresi dolmuş anahtarın oluşturanı yalnız bu nedenle bildirim almaz. Aynı kişi birden çok rolde olsa da tek e-posta alır. Oluşturma kaydı bulunmayan ya da oluşturanı artık kurumda etkin olmayan kurum düzeyi Webhook uçları için tahmini alıcıya e-posta gönderilmez; bu uçları kullanan istemciler kaldırmayı Değişiklik Günlüğü’nden izlemelidir.
OpenAPI açıklamasındaki politika, eski yol kaldırılmadan önce Sunset ve
ardıl sürümü gösteren Link (rel="successor-version") başlıklarının
kullanılmasını öngörür. Bu başlıklar her yanıta eklenmez; yalnız ilk gerçek
kaldırma kararında, kaldırılacak yolun yanıtlarına eklenir. Bugün duyurulmuş
bir kaldırma yoktur; mevcut yanıtlarda bu başlıklar bulunmaz. Eski ve yeni
sürümün paralel çalıştığı ya da bir geçiş tarihi bulunduğu, ilgili duyuru
yayımlanmadan varsayılmaz.
OpenAPI ve SDK Kapsamı
apps/api/openapi.json, seçilmiş geliştirici yollarının üretilmiş sözleşmesidir;
tüm uygulama yollarının envanteri değildir. Örneğin /health ve JWT korumalı
/api/v1/sources çalışır ancak bu izin listesinde bulunmaz.
SDK kapsamı ve sürümü kendi paket belgelerinden ayrıca kontrol edilir. OpenAPI çıktısının varlığı, her yol için SDK metodu üretildiğini veya paket kayıt sisteminde yayımlandığını kanıtlamaz.
Sözleşme kaynakları OpenAPI ve Sözleşme Dosyaları, müşteriye yönelik değişiklik kayıtları Değişiklik Günlüğü sayfasında açıklanır.