Ana içeriğe geç

Admin API Standards

Bu sayfa, admin endpoint ailesi için ortak calisma kurallarini tanimlar.

Auth ve Authorization​

Tum admin endpointleri icin taban kural:

  • admin auth zorunlu
  • JWT dogrulama zorunlu
  • session/auth context dogrulama zorunlu
  • actor kimligi audit alanlarina yansitilir

Yetki seviyesi 3 katmanda degerlendirilir:

  • global rol (users.role_id)
  • device-scoped authority (authorities)
  • action-scoped permission (authority_permissions)

Query Standardi​

List endpointlerinde asgari query modeli:

  • page: 1 tabanli sayfa numarasi
  • page_size: varsayilan 25, ust limit 100
  • sort: field:asc|desc
  • q: serbest metin arama
  • include_deleted: soft delete resource'larda opsiyonel

Filter isimleri resource semantigine gore genisletilebilir. Ornek:

  • status_id
  • role_id
  • device_id
  • user_id
  • is_active
  • owner
  • type
  • conversation_id

Response Envelope​

Basarili cevaplar icin onerilen genel yapi:

{
  "success": true,
  "data": {},
  "meta": {
    "request_id": "req_123",
    "cache": "hit",
    "page": 1,
    "page_size": 25,
    "total": 120
  }
}

List endpointlerinde data tipik olarak dizi olur. Detail endpointlerinde data tekil nesne olur.

Error Modeli​

Hata cevaplari icin onerilen genel yapi:

{
  "success": false,
  "error": {
    "code": "AUTHORITY_NOT_FOUND",
    "message": "Authority kaydi bulunamadi.",
    "details": {
      "authority_id": 44
    }
  },
  "meta": {
    "request_id": "req_123"
  }
}

HTTP Status Cizgisi​

  • 200 OK -> list/detail/update
  • 201 Created -> create
  • 202 Accepted -> async veya rebuild tetiklenen agir operasyonlar
  • 204 No Content -> idempotent delete/restore edge-case'leri
  • 400 Bad Request -> validation hatasi
  • 401 Unauthorized -> auth yok/gecersiz
  • 403 Forbidden -> rol veya permission yetersiz
  • 404 Not Found -> kayit bulunamadi
  • 409 Conflict -> unique, state transition veya semantic conflict
  • 422 Unprocessable Entity -> domain rule ihlali

Soft Delete Standardi​

Soft delete kullanan resource'larda:

  • varsayilan list filtreleri is_deleted = false
  • detail endpointi varsayilan olarak soft-deleted kaydi donmeyebilir
  • include_deleted=true admin/debug akisi icin acilabilir
  • restore gerekiyorsa POST /{resource}/{id}/restore tipi ozel endpoint dusunulur

Audit Standardi​

Mumkun olan her write isleminde su actor alanlari doldurulur:

  • created_by
  • updated_by
  • domaine gore assigned_by, granted_by, revoked_by

Append-only history gerektiren resource'larda mevcut kaydi mutate etmek yerine olay kaydi uretmek tercih edilir.

Redis ve DB Cizgisi​

  • DB authoritative source'tur
  • Redis cache/projection/runtime katmanidir
  • write basarili olduktan sonra Redis refresh/invalidate edilir
  • Redis rebuild basarisizligi DB write rollback sebebi degildir