2.3 KiB
API and Control Model
The current HTTP/JSON API is experimental and should be treated as a starting point, not a fixed FreeDMR 2 contract.
Current API Principles
- Local administration and automation.
- Not for public internet exposure.
- Small in-memory operations only.
- Bounded request bodies.
- No expensive live serialization of internal state.
- No blocking packet path.
- User-level authentication by connected peer/client session key.
- System-level authentication by system API key.
The API should bind to localhost by default unless explicitly configured otherwise.
FreeDMR 2 Direction
API operations should be bounded control-plane operations over access sessions, subscriptions, mesh peers, and reporting state.
Destructive system actions such as kill, resetall, and STUN clear should be separately enableable. Audit logs are required. Keys and secrets must never be logged.
Dashboard controls should use authenticated HTTP API operations unless a future UI genuinely needs bidirectional streaming.
Compatibility with the old API should be an adapter concern if needed.
The API may eventually run as a separate control-plane worker or sidecar. API requests should become ControlCommand messages sent to the owner of the relevant state.
The API must not directly mutate packet-plane state it does not own. Destructive operations must go through explicit owner-handled commands. API worker failure should not stop existing packet routing, although new control actions may fail until the worker recovers.
Suggested v2 Operations
GET /api/v2/health
GET /api/v2/version
GET /api/v2/state
GET /api/v2/client/{client_id}
GET /api/v2/client/{client_id}/slot/{slot}
POST /api/v2/client/{client_id}/slot/{slot}/subscriptions
DELETE /api/v2/client/{client_id}/slot/{slot}/subscriptions/{subscription_id}
POST /api/v2/mesh/{peer_id}/stun
DELETE /api/v2/mesh/{peer_id}/stun
POST /api/v2/system/reset
POST /api/v2/system/stop
Packet-Path Rule
API handlers must not perform work that delays packet routing. Expensive state export, dashboard compatibility, global reporting, and administrative analysis should use snapshots, bounded queues, or separate processes.
No API path should force expensive live serialization of packet-plane state.