User Roles List Endpoint

Bu sayfa, user_roles kayıtlarının listelenmesi için düşünülen endpoint sözleşmesinin ilk taslağını tanımlar.

Amaç

Bu endpointin amacı, admin yüzünde user_roles kayıtlarını filtrelenebilir ve sayfalanabilir şekilde listelemektir.

Bu endpoint:

• yönetim amaçlı listeleme sağlar
• tekil mutation yapmaz
• audit açısından yazma etkisi doğurmaz
• gerekiyorsa detay ekranları için özet veri kaynağı olur

Önerilen Route

GET /v1/admin/user-roles

Not: Bu ilk taslakta list ayrı doküman sayfası olarak tutulur. Gerçek HTTP route tarafında ayrı /list suffix'i önerilmez; koleksiyon route'u doğrudan listeleme için kullanılır.

Auth Gereksinimi

• admin auth zorunlu
• JWT doğrulama zorunlu
• session/auth context doğrulama zorunlu
• user_roles.read yetkisi zorunlu

Request

Query Parametreleri

Alan	Zorunlu	Açıklama
limit	Hayır	Sayfa boyutu, varsayılan 50, max 200
cursor	Hayır	Cursor-based pagination için imleç
q	Hayır	Serbest metin arama ifadesi
user_id	Hayır	Belirli kullanıcıya göre filtre
role_id	Hayır	Belirli role göre filtre
is_active	Hayır	Aktif/pasif filtre
sort	Hayır	Whitelist alanlarla sıralama

Örnek Request

GET /v1/admin/user-roles?limit=20&user_id=123&is_active=true
Authorization: Bearer <token>

Response

Başarılı Response

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": 91,
        "user_id": 123,
        "role_id": 7,
        "is_active": true,
        "created_at": "2026-04-20T06:00:00Z",
        "updated_at": "2026-04-20T06:00:00Z"
      }
    ],
    "pagination": {
      "next_cursor": "cur_abc123",
      "limit": 20,
      "has_more": true
    }
  },
  "error": null,
  "meta": {
    "request_id": "req_123",
    "timestamp": "2026-04-20T06:00:00Z"
  }
}

Veri Kaynağı

Bu endpoint için temel veri kaynağı:

• user_roles

Gerekirse join / enrich kaynakları:

• users
• roles

Read kuralı:

• önce ilgili Redis cache/projection kontrol edilir
• cache yoksa veya stale ise DB fallback yapılır
• DB sonucu ile Redis cache yeniden oluşturulur veya güncellenir

Not: Authoritative source DB'dir. Redis yalnız hızlandırıcı cache/projection katmanıdır.

Davranış Kuralları

• Varsayılan sıralama deterministic olmalıdır
• Cursor-based pagination tercih edilmelidir
• is_active filtresi hard delete dışında kalan aktif kayıt görünümü için kullanılabilir
• Çoklu filtre kullanımında whitelist yaklaşımı korunmalıdır

Hata Modeli

Durum	HTTP	error.code
Yetkisiz erişim	401	UNAUTHORIZED
Yetki yok	403	FORBIDDEN
Geçersiz query parametresi	400	VALIDATION_ERROR
İç hata	500	INTERNAL_ERROR

Netleşen Kararlar

Bu endpoint için şu kararlar kilitlenmiştir:

• user_roles dict/resource gibi ele alınır
• response içine user veya role özeti gömülmez
• authoritative source DB'dir
• read path Redis-first, miss/stale durumda DB fallback mantığıyla çalışır
• delete semantiği hard delete olarak ele alınır