Ana içeriğe geç
Mevzuat RadarDokümantasyon
Uygulamaya git ↗

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ğerAnlam
v1API yollarında kullanılan ana sürüm
1.0.0OpenAPI 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:

KanalKapsam
Değişiklik GünlüğüKaldırılan öğe, ardılı ve kaldırma tarihi
E-postaAş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.