API Servisi

API Servisi, mobil uygulama ve admin arayüzü için tek giriş backend katmanıdır.

V1 yaklaşımı: Admin backend API Servisi içinde tutulur; büyümede ayrı admin-backend servisine ayrılabilir.

Sorumluluk

• Mobil API ve Admin API endpointlerini sunmak
• AuthN/AuthZ (JWT + RBAC)
• Rule/action/recipient yönetim API’leri
• Cihaz/firmware/otomasyon yönetim API’leri
• Rate-limit, validation, idempotency, audit log

API Alanları

• /v1/app/* -> mobil istemci
• /v1/admin/* -> admin panel
• /v1/internal/* -> servisler arası (kısıtlı, service token)

İşlem Akışı

Güvenlik

• JWT access + refresh token
• RBAC rol seti: admin, operator, viewer
• Internal endpointlerde service-to-service token zorunlu
• Admin endpointlerde IP allowlist (opsiyonel)
• PII alanları log’da maskelenir
• Tüm değişikliklerde audit trail zorunlu

Versiyonlama ve Sözleşme

• API base version: /v1
• Breaking değişiklikte /v2 açılır
• Response envelope standardı:

{
  "ok": true,
  "data": {},
  "error": null,
  "meta": {
    "request_id": "req-...",
    "timestamp": "2026-03-12T21:00:00Z"
  }
}

Hata Modeli

Önerilen hata alanları:

• error.code (örn. VALIDATION_ERROR, FORBIDDEN, NOT_FOUND)
• error.message
• error.details (opsiyonel)
• meta.request_id

Pagination / Filtreleme Standardı

Liste endpointleri için:

• limit (varsayılan 50, max 200)
• cursor (cursor-based paging)
• sort (whitelist alanlar)

Idempotency

Yazma endpointlerinde Idempotency-Key header desteklenir:

• Aynı key + aynı payload -> aynı sonuç
• TTL önerisi: 24 saat

Event Entegrasyonu

API Servisi aşağıdaki işlemlerde event üretir:

• rule.updated.v1
• recipient.updated.v1
• automation.schedule.updated.v1
• firmware.released.v1

Not: Event payload standardı arşiv referansı: /projects/cinga/backend/architecture/event-envelope.

Örnek Endpointler

• POST /v1/admin/rules/groups
• PUT /v1/admin/rules/groups/{id}
• POST /v1/admin/recipients/profiles
• POST /v1/admin/automation/jobs
• POST /v1/admin/firmware/releases
• GET /v1/app/devices/{device_id}/status
• GET /v1/app/devices/{device_id}/windows/latest

SLO (Öneri)

Metrik	Hedef
p95 latency	< 300ms
error_rate	< 1%
auth_fail_rate	izlenir
p95 admin write	< 500ms

Çıktı

• Mobil/admin kullanım API katmanı
• Yönetim operasyonları için tek kontrol yüzeyi