From 0139169c7d36b682d23ab2cd7b0062f8c3d03243 Mon Sep 17 00:00:00 2001 From: Joel Krauska Date: Mon, 3 Nov 2025 14:50:43 -0800 Subject: [PATCH] more doc tidy --- README.md | 6 ++ docs/API_Documentation.md | 159 ++++++++++++++++++++++++++++++++++++++ docs/README.md | 3 +- 3 files changed, 167 insertions(+), 1 deletion(-) create mode 100644 docs/API_Documentation.md diff --git a/README.md b/README.md index 125d1a5..0dab398 100644 --- a/README.md +++ b/README.md @@ -413,3 +413,9 @@ Add schedule to the bottom of the file (modify /path/to/file/ to the correct pat ``` Check the log file to see it the script run at the specific time. + +--- + +## Technical Documentation + +For more detailed technical documentation including database migrations, architecture details, and advanced topics, see the [docs/](docs/) directory. diff --git a/docs/API_Documentation.md b/docs/API_Documentation.md new file mode 100644 index 0000000..6b7e909 --- /dev/null +++ b/docs/API_Documentation.md @@ -0,0 +1,159 @@ + +# 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!" + } + ] +} +``` + +--- + +### 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. + +## 4 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... + ] +} diff --git a/docs/README.md b/docs/README.md index 9166142..84febc3 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,11 +2,12 @@ This directory contains technical documentation for MeshView that goes beyond initial setup and basic usage. -These documents are intended for developers, contributors, and advanced users who need deeper insight into the system's architecture, database migrations, and internal workings. +These documents are intended for developers, contributors, and advanced users who need deeper insight into the system's architecture, database migrations, API endpoints, and internal workings. ## Contents - [ALEMBIC_SETUP.md](ALEMBIC_SETUP.md) - Database migration setup and management - [TIMESTAMP_MIGRATION.md](TIMESTAMP_MIGRATION.md) - Details on timestamp schema changes +- **API Documentation** - REST API endpoints and usage (coming soon) For initial setup and basic usage instructions, please see the main [README.md](../README.md) in the root directory.