You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
53 lines
2.3 KiB
53 lines
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
|
|
|
|
```text
|
|
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.
|