API Architecture & Route Conventions

The RUSEON Core API subsystem is built on a high-throughput Gin HTTP framework and a concurrent gRPC server engine (internal/api/router.go).

---

1. Route Namespace Architecture

RUSEON Core organizes HTTP endpoints into clear functional namespaces:

Namespace Pattern	Authentication	Purpose
/api/*	JWT Bearer / Public (/api/login)	Camera provisioning, user management, tags, folders, system backup
/stream/*	Public or 60s Stream Token	Real-time live media delivery (WHEP WebRTC, WebCodecs WebSocket, HLS)
/hls/*	Public / Token	Dynamic on-demand archive playback (archive.m3u8, segment.ts)
/models/*	Public	Cached ONNX AI weights distribution hub (GET /models/:filename)
/livez, /readyz	Public	Kubernetes / Container health and readiness probes
/metrics	Public / Scraper	Standard Prometheus metrics exporter

---

2. Standard JSON Responses & Error Format

Endpoints return direct, structured JSON objects.

Example Success Response (POST /api/login):

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Example Error Response:

{
  "error": "camera not found"
}

Standard Status Codes:

• 200 OK: Request succeeded.
• 201 Created: Entity (camera, user, tag, folder) created or WebRTC WHEP session initialized.
• 400 Bad Request: Invalid JSON body or malformed parameters.
• 401 Unauthorized: Missing or expired JWT / stream token.
• 403 Forbidden: Insufficient RBAC role permissions.
• 404 Not Found: Requested camera, user, or archive file does not exist.
• 500 Internal Server Error: Storage failure or engine error.

---

3. Real-Time Log Streaming (SSE)

Admins and operators can subscribe to server log events via Server-Sent Events (SSE):

GET /api/logs/stream
Authorization: Bearer <JWT_TOKEN>
Accept: text/event-stream

Related Documentation

• API Hub
• REST API Reference
• Authentication API Guide
• gRPC Pipeline Guide