forked from iarv/meshview
345 lines
7.4 KiB
Markdown
345 lines
7.4 KiB
Markdown
|
|
# API Documentation
|
|
|
|
## 1. Chat API
|
|
|
|
### GET `/api/chat`
|
|
Returns the most recent chat messages.
|
|
|
|
**Query Parameters**
|
|
- `limit` (optional, int): Maximum number of messages to return. Default: `100`.
|
|
|
|
**Response Example**
|
|
```json
|
|
{
|
|
"packets": [
|
|
{
|
|
"id": 123,
|
|
"import_time": "2025-07-22T12:45:00",
|
|
"from_node_id": 987654,
|
|
"from_node": "Alice",
|
|
"channel": "main",
|
|
"payload": "Hello, world!"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
### GET `/api/chat/updates`
|
|
Returns chat messages imported after a given timestamp.
|
|
|
|
**Query Parameters**
|
|
- `last_time` (optional, ISO timestamp): Only messages imported after this time are returned.
|
|
|
|
**Response Example**
|
|
```json
|
|
{
|
|
"packets": [
|
|
{
|
|
"id": 124,
|
|
"import_time": "2025-07-22T12:50:00",
|
|
"from_node_id": 987654,
|
|
"from_node": "Alice",
|
|
"channel": "main",
|
|
"payload": "New message!"
|
|
}
|
|
],
|
|
"latest_import_time": "2025-07-22T12:50:00"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Nodes API
|
|
|
|
### GET `/api/nodes`
|
|
Returns a list of all nodes, with optional filtering by last seen.
|
|
|
|
**Query Parameters**
|
|
- `hours` (optional, int): Return nodes seen in the last N hours.
|
|
- `days` (optional, int): Return nodes seen in the last N days.
|
|
- `last_seen_after` (optional, ISO timestamp): Return nodes seen after this time.
|
|
|
|
**Response Example**
|
|
```json
|
|
{
|
|
"nodes": [
|
|
{
|
|
"node_id": 1234,
|
|
"long_name": "Alice",
|
|
"short_name": "A",
|
|
"channel": "main",
|
|
"last_seen": "2025-07-22T12:40:00",
|
|
"hardware": "T-Beam",
|
|
"firmware": "1.2.3",
|
|
"role": "client",
|
|
"last_lat": 37.7749,
|
|
"last_long": -122.4194
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Packets API
|
|
|
|
### GET `/api/packets`
|
|
Returns a list of packets with optional filters.
|
|
|
|
**Query Parameters**
|
|
- `limit` (optional, int): Maximum number of packets to return. Default: `200`.
|
|
- `since` (optional, ISO timestamp): Only packets imported after this timestamp are returned.
|
|
|
|
**Response Example**
|
|
```json
|
|
{
|
|
"packets": [
|
|
{
|
|
"id": 123,
|
|
"from_node_id": 5678,
|
|
"to_node_id": 91011,
|
|
"portnum": 1,
|
|
"import_time": "2025-07-22T12:45:00",
|
|
"payload": "Hello, Bob!"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
---
|
|
|
|
## 4. Channels API
|
|
|
|
### GET `/api/channels`
|
|
Returns a list of channels seen in a given time period.
|
|
|
|
**Query Parameters**
|
|
- `period_type` (optional, string): Time granularity (`hour` or `day`). Default: `hour`.
|
|
- `length` (optional, int): Number of periods to look back. Default: `24`.
|
|
|
|
**Response Example**
|
|
```json
|
|
{
|
|
"channels": ["LongFast", "MediumFast", "ShortFast"]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Statistics API
|
|
|
|
### GET `/api/stats`
|
|
|
|
Retrieve packet statistics aggregated by time periods, with optional filtering.
|
|
|
|
---
|
|
|
|
## Query Parameters
|
|
|
|
| Parameter | Type | Required | Default | Description |
|
|
|--------------|---------|----------|----------|-------------------------------------------------------------------------------------------------|
|
|
| `period_type` | string | No | `hour` | Time granularity of the stats. Allowed values: `hour`, `day`. |
|
|
| `length` | integer | No | 24 | Number of periods to include (hours or days). |
|
|
| `channel` | string | No | — | Filter results by channel name (case-insensitive). |
|
|
| `portnum` | integer | No | — | Filter results by port number. |
|
|
| `to_node` | integer | No | — | Filter results to packets sent **to** this node ID. |
|
|
| `from_node` | integer | No | — | Filter results to packets sent **from** this node ID. |
|
|
|
|
---
|
|
|
|
## Response
|
|
|
|
```json
|
|
{
|
|
"period_type": "hour",
|
|
"length": 24,
|
|
"channel": "LongFast",
|
|
"portnum": 1,
|
|
"to_node": 12345678,
|
|
"from_node": 87654321,
|
|
"data": [
|
|
{
|
|
"period": "2025-08-08 14:00",
|
|
"count": 10
|
|
},
|
|
{
|
|
"period": "2025-08-08 15:00",
|
|
"count": 7
|
|
}
|
|
// more entries...
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Edges API
|
|
|
|
### GET `/api/edges`
|
|
Returns network edges (connections between nodes) based on traceroutes and neighbor info.
|
|
|
|
**Query Parameters**
|
|
- `type` (optional, string): Filter by edge type (`traceroute` or `neighbor`). If omitted, returns both types.
|
|
|
|
**Response Example**
|
|
```json
|
|
{
|
|
"edges": [
|
|
{
|
|
"from": 12345678,
|
|
"to": 87654321,
|
|
"type": "traceroute"
|
|
},
|
|
{
|
|
"from": 11111111,
|
|
"to": 22222222,
|
|
"type": "neighbor"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Configuration API
|
|
|
|
### GET `/api/config`
|
|
Returns the current site configuration (safe subset exposed to clients).
|
|
|
|
**Response Example**
|
|
```json
|
|
{
|
|
"site": {
|
|
"domain": "meshview.example.com",
|
|
"language": "en",
|
|
"title": "Bay Area Mesh",
|
|
"message": "Real time data from around the bay area",
|
|
"starting": "/chat",
|
|
"nodes": "true",
|
|
"conversations": "true",
|
|
"everything": "true",
|
|
"graphs": "true",
|
|
"stats": "true",
|
|
"net": "true",
|
|
"map": "true",
|
|
"top": "true",
|
|
"map_top_left_lat": 39.0,
|
|
"map_top_left_lon": -123.0,
|
|
"map_bottom_right_lat": 36.0,
|
|
"map_bottom_right_lon": -121.0,
|
|
"map_interval": 3,
|
|
"firehose_interval": 3,
|
|
"weekly_net_message": "Weekly Mesh check-in message.",
|
|
"net_tag": "#BayMeshNet",
|
|
"version": "2.0.8 ~ 10-22-25"
|
|
},
|
|
"mqtt": {
|
|
"server": "mqtt.bayme.sh",
|
|
"topics": ["msh/US/bayarea/#"]
|
|
},
|
|
"cleanup": {
|
|
"enabled": "false",
|
|
"days_to_keep": "14",
|
|
"hour": "2",
|
|
"minute": "0",
|
|
"vacuum": "false"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Language/Translations API
|
|
|
|
### GET `/api/lang`
|
|
Returns translation strings for the UI.
|
|
|
|
**Query Parameters**
|
|
- `lang` (optional, string): Language code (e.g., `en`, `es`). Defaults to site language setting.
|
|
- `section` (optional, string): Specific section to retrieve translations for.
|
|
|
|
**Response Example (full)**
|
|
```json
|
|
{
|
|
"chat": {
|
|
"title": "Chat",
|
|
"send": "Send"
|
|
},
|
|
"map": {
|
|
"title": "Map",
|
|
"zoom_in": "Zoom In"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Response Example (section-specific)**
|
|
Request: `/api/lang?section=chat`
|
|
```json
|
|
{
|
|
"title": "Chat",
|
|
"send": "Send"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 9. Health Check API
|
|
|
|
### GET `/health`
|
|
Health check endpoint for monitoring, load balancers, and orchestration systems.
|
|
|
|
**Response Example (Healthy)**
|
|
```json
|
|
{
|
|
"status": "healthy",
|
|
"timestamp": "2025-11-03T14:30:00.123456Z",
|
|
"version": "3.0.0",
|
|
"git_revision": "6416978",
|
|
"database": "connected",
|
|
"database_size": "853.03 MB",
|
|
"database_size_bytes": 894468096
|
|
}
|
|
```
|
|
|
|
**Response Example (Unhealthy)**
|
|
Status Code: `503 Service Unavailable`
|
|
```json
|
|
{
|
|
"status": "unhealthy",
|
|
"timestamp": "2025-11-03T14:30:00.123456Z",
|
|
"version": "2.0.8",
|
|
"git_revision": "6416978",
|
|
"database": "disconnected"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 10. Version API
|
|
|
|
### GET `/version`
|
|
Returns detailed version information including semver, release date, and git revision.
|
|
|
|
**Response Example**
|
|
```json
|
|
{
|
|
"version": "2.0.8",
|
|
"release_date": "2025-10-22",
|
|
"git_revision": "6416978a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q",
|
|
"git_revision_short": "6416978"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Notes
|
|
- All timestamps (`import_time`, `last_seen`) are returned in ISO 8601 format.
|
|
- `portnum` is an integer representing the packet type.
|
|
- `payload` is always a UTF-8 decoded string.
|
|
- Node IDs are integers (e.g., `12345678`).
|