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

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 ailesiKimlik doğrulamaKapsam
/api/v1/public/regulations, /api/v1/public/source-statsGerekmezHerkese açık okuma
Müşteri API’six-api-key veya desteklenen yollarda Bearer JWTAnahtar izinleri, kurum ve endpoint denetimleri uygulanır
/api/v1/webhooks* yönetimiAuthorization: Bearer <JWT>Kurum ADMIN rolü; okuma için settings:read, değişiklikler için settings:write
/api/v1/sourcesBearer JWTOturumun 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

AlanAnlam
pageDesteklenen listelerde 1 tabanlı sayfa numarası
limitVarsayılanı ve üst sınırı endpoint özelinde belirlenir
hasMoreDöndüğünde sonraki sayfanın varlığını gösterir
totalIsEstimatedtrue ise total kesin kayıt sayısı değildir
sort, orderYalnı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ışı
400Sorgu veya gövde düzeltilir; aynı geçersiz istek tekrarlanmaz
401Oturum veya anahtar geçerliliği kontrol edilir
403Rol, izin ve erişim politikası kontrol edilir
404Yol veya kaydın varlığı kontrol edilir
429Retry-After ve varsa gövdedeki retryAfterSeconds dikkate alınır
5xxGeç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.