Ortak API Kuralları
Bu sayfa herkese açık arşiv, müşteri API’si ve Webhook yönetimi için ortak
kuralları açıklar. Yanıtın data yapısı ve izinler endpoint bazında değişir.
Temel URL
Canlı API adresi https://api.mevzuatradar.com olarak tanımlıdır.
Örneğin arşiv yolu https://api.mevzuatradar.com/api/v1/public/regulations
olur. Sürüm öneki her yolun parçasıdır; sağlık yollarına eklenmez.
Test bağlantısı için Entegrasyon Testi sayfası kullanılır.
Kimlik Doğrulama
| Endpoint ailesi | Kimlik doğrulama | Kapsam |
|---|---|---|
/api/v1/public/regulations, /api/v1/public/source-stats | Gerekmez | Herkese açık okuma |
| Müşteri API’si | x-api-key veya desteklenen yollarda Bearer JWT | Anahtar izinleri, kurum ve endpoint denetimleri uygulanır |
/api/v1/webhooks* yönetimi | Authorization: Bearer <JWT> | Kurum ADMIN rolü; okuma için settings:read, değişiklikler için settings:write |
/api/v1/sources | Bearer JWT | Oturumun kurumuna göre isAccessible döner |
API anahtarları uygulamadaki /settings/api sayfasından yönetilir.
Bir yolun /api/v1 altında olması, kimliksiz erişilebildiği anlamına gelmez.
Gizli değerler repo, destek kaydı veya log içine yazılmaz.
Yanıt Zarfı
Global dönüştürücü standart JSON başarı yanıtlarını şu biçimde sarar:
{ "success": true, "data": {} }Global dönüştürücü üst düzey meta eklemez. Controller sayfalama bilgisi
döndürüyorsa bu bilgi data içinde kalır. Endpoint sözleşmesine göre
data.items yanında data.total, data.page, data.limit, data.totalPages
veya data.meta bulunabilir. Dizi döndüren endpointlerde data doğrudan dizidir.
Sağlık yolları (/health, /health/live, /health/ready), /scim/v2 ailesi,
OpenAPI yolları, HTML yanıtları ve StreamableFile dosya yanıtları bu
sarmalamadan muaftır. Hazırlık kontrolünün 503 yanıtı da sağlık gövdesidir;
Problem Details zarfına dönüştürülmez.
Sayfalama ve Sorgu Doğrulama
| Alan | Anlam |
|---|---|
page | Desteklenen listelerde 1 tabanlı sayfa numarası |
limit | Varsayılanı ve üst sınırı endpoint özelinde belirlenir |
hasMore | Döndüğünde sonraki sayfanın varlığını gösterir |
totalIsEstimated | true ise total kesin kayıt sayısı değildir |
sort, order | Yalnız ilgili endpoint destekliyorsa gönderilir |
Herkese Açık Mevzuat Arşivi kesin toplam
hesaplamaz; sayfalar hasMore ile ilerletilir. items.length === limit
koşulu tek başına sonraki sayfanın varlığını kanıtlamaz.
DTO ile doğrulanan isteklerde bilinmeyen alanlar HTTP 400 ile reddedilir. Bu nedenle bir endpointin filtresi başka bir endpointe otomatik taşınmaz.
Tarih ve Kod Alanları
Zaman damgaları (publishedAt, generatedAt, lastUpdated, timestamp)
JSON’da ISO-8601 biçiminde, örneklerde UTC Z ekiyle gösterilir. Bu kural
her tarih metnine uygulanmaz: arşivde officialDate kaynak metnidir;
yoksa publishedAt üzerinden Europe/Istanbul saat diliminde gg.aa.yyyy
olarak üretilir.
sourceType, sourceCode, sourceCategory, sourceSubcategory ve
legalDocumentClass makine kodlarıdır. Arşivde sağlanan *Label alanları
ve Resmi Kaynaklar tablosu gösterim için kullanılabilir.
Hata Biçimi
Global hata filtresinden geçen hatalar
Content-Type: application/problem+json; charset=utf-8 ile RFC 9457
Problem Details alanlarını ve geriye uyumluluk alanlarını birlikte döndürür.
Aşağıdaki gövde, bulunmayan OpenAPI yolu için şema örneğidir; kimlikler ve
zaman damgası örnektir:
{
"type": "https://mevzuatradar.com/problems/not_found",
"title": "Not Found",
"status": 404,
"detail": "Cannot GET /api/docs-json",
"instance": "/api/docs-json",
"requestId": "dc05fc79-568e-4813-b577-ef1fcf4b1849",
"errorId": "5d3fb85b-bb86-4209-8f42-3ba03d76f5a3",
"errorCode": "NOT_FOUND",
"timestamp": "2026-10-24T19:23:20.818Z",
"success": false,
"error": "Cannot GET /api/docs-json",
"statusCode": 404,
"path": "/api/docs-json"
}error, statusCode ve path, sırasıyla detail, status ve instance
alanlarının uyumluluk karşılıklarıdır. title İngilizce olabilir.
DTO doğrulama hatalarında varsayılan kod BAD_REQUEST, HTTP durumu 400’dür.
errorCode, hatayı üreten kod tarafından ayrıca belirlenebilir.
5xx hata ayrıntıları genel bir Türkçe mesajla maskelenir.
| HTTP durumu | İstemci davranışı |
|---|---|
400 | Sorgu veya gövde düzeltilir; aynı geçersiz istek tekrarlanmaz |
401 | Oturum veya anahtar geçerliliği kontrol edilir |
403 | Rol, izin ve erişim politikası kontrol edilir |
404 | Yol veya kaydın varlığı kontrol edilir |
429 | Retry-After ve varsa gövdedeki retryAfterSeconds dikkate alınır |
5xx | Geçici hata için okuma tekrarları sınırlı beklemeyle yapılır; yazma tekrarı endpointin tekillik sözleşmesine bağlıdır |
Bu biçim uygulama hata filtresinin sözleşmesidir. OpenAPI Basic kimlik doğrulama reddi düz metin olabilir; ağ geçidi hatalarının aynı JSON biçimini kullanması garanti edilmez.
İstek Korelasyonu
Uygulama ara katmanı X-Request-Id ve X-Correlation-Id döndürür.
Gelen x-request-id, yoksa x-correlation-id kullanılır; ikisi de yoksa UUID
üretilir. Gelen değer kırpılır ve en fazla 120 karakter alınır.
Global hata filtresi ayrıca X-Error-Id döndürür. Destek kaydında bu kimlikler,
endpoint, zaman ve HTTP durumu paylaşılır; gizli değerler paylaşılmaz.