12a51a5ebe
- Create docs/ with 7 focused files: architecture, api, scoring, agent, deployment, freeswitch, development - Rewrite README.md as concise overview with links to docs/ - Remove AGENTS.md (content merged into docs/ and README)
139 lines
4.1 KiB
Markdown
139 lines
4.1 KiB
Markdown
# API Reference
|
||
|
||
## Authentication
|
||
|
||
| Method | Path | Auth | Description |
|
||
|--------|------|------|-------------|
|
||
| `POST` | `/api/auth/login` | – | Login: `{"username":"admin","password":"admin"}` → `access_token` + `refresh_token` |
|
||
| `POST` | `/api/auth/refresh` | – | Refresh access token using `refresh_token` |
|
||
|
||
All endpoints except `/api/route`, `/api/health/*`, `/api/monitoring/*` require `Authorization: Bearer <jwt>`.
|
||
|
||
Roles: `admin` (full access), `viewer` (read-only nodes/metrics).
|
||
|
||
## Core
|
||
|
||
| Method | Path | Auth | Description |
|
||
|--------|------|------|-------------|
|
||
| `GET` | `/api/route` | – | Route a call. Query: `caller_id`, `dest`, `ingress_trunk` |
|
||
| `GET` | `/api/health` | – | Stats: total nodes, healthy, requests, uptime |
|
||
| `GET` | `/api/health/live` | – | Liveness probe (always 200) |
|
||
| `GET` | `/api/health/ready` | – | Readiness probe (NATS + metrics) |
|
||
|
||
### Route Response (success)
|
||
|
||
```json
|
||
{ "node_id": "pbx-03", "score": 88, "sip_gateway": "sip:pbx03.lan:5060" }
|
||
```
|
||
|
||
### Route Response (fallback — all nodes unhealthy)
|
||
|
||
```json
|
||
{
|
||
"fallback": true,
|
||
"sip_gateway": "sip:operator.lan:5060",
|
||
"reason": "all_nodes_unhealthy",
|
||
"nodes": [...]
|
||
}
|
||
```
|
||
|
||
### Route Response (no nodes registered)
|
||
|
||
```json
|
||
{ "error": "no_nodes_registered" }
|
||
```
|
||
|
||
## Nodes
|
||
|
||
| Method | Path | Role | Description |
|
||
|--------|------|------|-------------|
|
||
| `GET` | `/api/nodes` | admin/viewer | List all nodes with scores and state |
|
||
| `GET` | `/api/nodes/{id}/metrics` | admin/viewer | Metrics history (ring buffer, ~30 min) |
|
||
| `PUT` | `/api/nodes/{id}/toggle` | admin | `{"disabled":true, "reason":"..."}` |
|
||
|
||
## Trunks
|
||
|
||
| Method | Path | Role | Description |
|
||
|--------|------|------|-------------|
|
||
| `GET` | `/api/trunks` | admin | All trunks. Query: `type=ingress\|balance\|fallback` |
|
||
| `POST` | `/api/trunks` | admin | Create trunk |
|
||
| `PUT` | `/api/trunks/{id}` | admin | Update trunk |
|
||
| `DELETE` | `/api/trunks/{id}` | admin | Delete trunk |
|
||
|
||
Trunk model:
|
||
```json
|
||
{
|
||
"id": "trk-001",
|
||
"name": "pbx-03 balance",
|
||
"type": "ingress|balance|fallback",
|
||
"node_id": "pbx-03",
|
||
"gateway": "sip:pbx03.lan:5060",
|
||
"codecs": ["PCMU", "PCMA"],
|
||
"context": "default",
|
||
"enabled": true,
|
||
"description": "",
|
||
"created_at": "...",
|
||
"updated_at": "..."
|
||
}
|
||
```
|
||
|
||
Trunk types:
|
||
|
||
| Type | Purpose | Quantity |
|
||
|------|---------|----------|
|
||
| `ingress` | Incoming trunk (where calls come from) | 1..N |
|
||
| `balance` | Destination trunk (bound to a Node) | 1..N |
|
||
| `fallback` | Operator fallback (when all balance score < 0) | exactly 1 |
|
||
|
||
## Users (admin only)
|
||
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| `GET` | `/api/users` | List users |
|
||
| `POST` | `/api/users` | Create user |
|
||
| `PUT` | `/api/users/{id}` | Update user |
|
||
| `DELETE` | `/api/users/{id}` | Delete user |
|
||
|
||
Note: `user-01` (primary admin) cannot be deleted or demoted to viewer.
|
||
|
||
## Monitoring (API-key auth)
|
||
|
||
Use `X-API-Key` header (not JWT).
|
||
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| `GET` | `/api/monitoring/zabbix` | JSON for Zabbix LLD + items |
|
||
| `GET` | `/api/monitoring/prometheus` | `text/plain` metrics for Prometheus |
|
||
|
||
## WebSocket
|
||
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| `WS` | `/ws/metrics` | Real-time metrics stream for frontend (JWT in query `?token=`) |
|
||
|
||
## Examples
|
||
|
||
```bash
|
||
# Route (no auth)
|
||
curl 'http://localhost:8080/api/route?caller_id=74951234567&dest=123&ingress_trunk=trk-001'
|
||
# → {"node_id":"pbx-03","score":88,"sip_gateway":"sip:pbx03.lan:5060"}
|
||
|
||
# Login
|
||
TOKEN=$(curl -s -X POST http://localhost:8080/api/auth/login \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"username":"admin","password":"admin"}' | jq -r '.access_token')
|
||
|
||
# Nodes with JWT
|
||
curl -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/nodes
|
||
|
||
# Toggle node (admin only)
|
||
curl -X PUT http://localhost:8080/api/nodes/pbx-01/toggle \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-H 'Content-Type: application/json' \
|
||
-d '{"disabled":true,"reason":"maintenance"}'
|
||
|
||
# Prometheus metrics (API-key)
|
||
curl -H "X-API-Key: $(jq -r '.monitoring_api_key' data/config.json)" \
|
||
http://localhost:8080/api/monitoring/prometheus
|
||
```
|