From 40e9fbdb3fca10f8c229c7d367f969fa7524857e Mon Sep 17 00:00:00 2001 From: jokob-sk Date: Sun, 24 Aug 2025 13:12:33 +1000 Subject: [PATCH] docs --- docs/API.md | 4 + docs/API_EVENTS.md | 2 +- docs/API_ONLINEHISTORY.md | 29 +----- docs/API_SESSIONS.md | 183 +++++++++++++++++++++++++++++++++++--- docs/API_SYNC.md | 72 +++++++++++---- 5 files changed, 233 insertions(+), 57 deletions(-) diff --git a/docs/API.md b/docs/API.md index cd6fbe4f..f5f5ba3f 100755 --- a/docs/API.md +++ b/docs/API.md @@ -51,6 +51,10 @@ http://:/ ## Endpoints + +> [!TIP] +> When retrieving devices try using the GraphQL API endpoint first as it is read-optimized. + * [Device API Endpoints](API_DEVICE.md) – Manage individual devices * [Devices Collection](API_DEVICES.md) – Bulk operations on multiple devices * [Events](API_EVENTS.md) – Device event logging and management diff --git a/docs/API_EVENTS.md b/docs/API_EVENTS.md index 15fb949f..c845e10d 100755 --- a/docs/API_EVENTS.md +++ b/docs/API_EVENTS.md @@ -82,7 +82,7 @@ The Events API provides access to **device event logs**, allowing creation, retr ```json { "success": true, - "message": "Deleted events older than 30 days" + "message": "Deleted events older than days" } ``` diff --git a/docs/API_ONLINEHISTORY.md b/docs/API_ONLINEHISTORY.md index fee2926b..6a3afbff 100755 --- a/docs/API_ONLINEHISTORY.md +++ b/docs/API_ONLINEHISTORY.md @@ -29,31 +29,4 @@ Manage the **online history records** of devices. Currently, the API supports de ```bash curl -X DELETE "http://:/history" \ -H "Authorization: Bearer " -``` - ---- - -### Implementation Details - -The endpoint calls the helper function `delete_online_history()`: - -```python -def delete_online_history(): - """Delete all online history activity""" - - conn = get_temp_db_connection() - cur = conn.cursor() - - # Remove all entries from Online_History table - cur.execute("DELETE FROM Online_History") - - conn.commit() - conn.close() - - return jsonify({"success": True, "message": "Deleted online history"}) -``` - -* Opens a temporary database connection for the request. -* Executes a **full table delete** (`DELETE FROM Online_History`). -* Commits the transaction and closes the connection. -* Returns a JSON confirmation message. +``` \ No newline at end of file diff --git a/docs/API_SESSIONS.md b/docs/API_SESSIONS.md index 7fbbe5cc..a9412120 100755 --- a/docs/API_SESSIONS.md +++ b/docs/API_SESSIONS.md @@ -1,18 +1,181 @@ -# SEssions API Endpoints +# Sessions API Endpoints -Track device connection sessions. +Track and manage device connection sessions. Sessions record when a device connects or disconnects on the network. -* **POST** `/sessions/create` → Create a new session +### Create a Session + +* **POST** `/sessions/create` → Create a new session for a device + + **Request Body:** ```json - { "mac": "AA:BB:CC:DD:EE:FF", "ip": "192.168.1.10", "start_time": "2025-08-01T10:00:00" } + { + "mac": "AA:BB:CC:DD:EE:FF", + "ip": "192.168.1.10", + "start_time": "2025-08-01T10:00:00", + "end_time": "2025-08-01T12:00:00", // optional + "event_type_conn": "Connected", // optional, default "Connected" + "event_type_disc": "Disconnected" // optional, default "Disconnected" + } ``` -* **DELETE** `/sessions/delete` → Delete session by MAC + + **Response:** ```json - { "mac": "AA:BB:CC:DD:EE:FF" } + { + "success": true, + "message": "Session created for MAC AA:BB:CC:DD:EE:FF" + } ``` -* **GET** `/sessions/list?mac=&start_date=2025-08-01&end_date=2025-08-21` → List sessions -* **GET** `/sessions/calendar?start=2025-08-01&end=2025-08-21` → Calendar view of sessions -* **GET** `/sessions/?period=1 day` → Sessions for a device -* **GET** `/sessions/session-events?type=all&period=7 days` → Session events summary \ No newline at end of file + +--- + +### Delete Sessions + +* **DELETE** `/sessions/delete` → Delete all sessions for a given MAC + + **Request Body:** + + ```json + { + "mac": "AA:BB:CC:DD:EE:FF" + } + ``` + + **Response:** + + ```json + { + "success": true, + "message": "Deleted sessions for MAC AA:BB:CC:DD:EE:FF" + } + ``` + +--- + +### List Sessions + +* **GET** `/sessions/list` → Retrieve sessions optionally filtered by device and date range + + **Query Parameters:** + + * `mac` (optional) → Filter by device MAC address + * `start_date` (optional) → Filter sessions starting from this date (`YYYY-MM-DD`) + * `end_date` (optional) → Filter sessions ending by this date (`YYYY-MM-DD`) + + **Example:** + + ``` + /sessions/list?mac=AA:BB:CC:DD:EE:FF&start_date=2025-08-01&end_date=2025-08-21 + ``` + + **Response:** + + ```json + { + "success": true, + "sessions": [ + { + "ses_MAC": "AA:BB:CC:DD:EE:FF", + "ses_Connection": "2025-08-01 10:00", + "ses_Disconnection": "2025-08-01 12:00", + "ses_Duration": "2h 0m", + "ses_IP": "192.168.1.10", + "ses_Info": "" + } + ] + } + ``` + +--- + +### Calendar View of Sessions + +* **GET** `/sessions/calendar` → View sessions in calendar format + + **Query Parameters:** + + * `start` → Start date (`YYYY-MM-DD`) + * `end` → End date (`YYYY-MM-DD`) + + **Example:** + + ``` + /sessions/calendar?start=2025-08-01&end=2025-08-21 + ``` + + **Response:** + + ```json + { + "success": true, + "sessions": [ + { + "resourceId": "AA:BB:CC:DD:EE:FF", + "title": "", + "start": "2025-08-01T10:00:00", + "end": "2025-08-01T12:00:00", + "color": "#00a659", + "tooltip": "Connection: 2025-08-01 10:00\nDisconnection: 2025-08-01 12:00\nIP: 192.168.1.10", + "className": "no-border" + } + ] + } + ``` + +--- + +### Device Sessions + +* **GET** `/sessions/` → Retrieve sessions for a specific device + + **Query Parameters:** + + * `period` → Period to retrieve sessions (`1 day`, `7 days`, `1 month`, etc.) + Default: `1 day` + + **Example:** + + ``` + /sessions/AA:BB:CC:DD:EE:FF?period=7 days + ``` + + **Response:** + + ```json + { + "success": true, + "sessions": [ + { + "ses_MAC": "AA:BB:CC:DD:EE:FF", + "ses_Connection": "2025-08-01 10:00", + "ses_Disconnection": "2025-08-01 12:00", + "ses_Duration": "2h 0m", + "ses_IP": "192.168.1.10", + "ses_Info": "" + } + ] + } + ``` + +--- + +### Session Events Summary + +* **GET** `/sessions/session-events` → Retrieve a summary of session events + + **Query Parameters:** + + * `type` → Event type (`all`, `sessions`, `missing`, `voided`, `new`, `down`) + Default: `all` + * `period` → Period to retrieve events (`7 days`, `1 month`, etc.) + + **Example:** + + ``` + /sessions/session-events?type=all&period=7 days + ``` + + **Response:** + Returns a list of events or sessions with formatted connection, disconnection, duration, and IP information. + diff --git a/docs/API_SYNC.md b/docs/API_SYNC.md index 082c4002..096f6bf8 100755 --- a/docs/API_SYNC.md +++ b/docs/API_SYNC.md @@ -35,35 +35,71 @@ curl 'http://:/sync' \ --- -#### 9.2 POST `/sync` +#### 9.2 POST `/sync` -Used by a node to send data to the hub. The hub receives **form-encoded data** and stores it for processing. +The **POST** endpoint is used by nodes to **send data to the hub**. The hub expects the data as **form-encoded fields** (application/x-www-form-urlencoded or multipart/form-data). The hub then stores the data in the plugin log folder for processing. -**Required Form Fields:** +#### Required Fields -| Field | Description | -| ----------- | ----------------------------------- | -| `data` | The payload (plain text or JSON) | -| `node_name` | Name of the node sending the data | -| `plugin` | The plugin name generating the data | +| Field | Type | Description | +| ----------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `data` | string | The payload from the plugin or devices. Typically **plain text**, **JSON**, or **encrypted Base64** data. In your Python script, `encrypt_data()` is applied before sending. | +| `node_name` | string | The name of the node sending the data. Matches the node’s `SYNC_node_name` setting. Used to generate the filename on the hub. | +| `plugin` | string | The name of the plugin sending the data. Determines the filename prefix (`last_result....`). | +| `file_path` | string (optional) | Path of the local file being sent. Used only for logging/debugging purposes on the hub; **not required for processing**. | -**Example Request (cURL):** +--- -```sh -curl -X POST 'http://:/sync' \ +### How the Hub Processes the POST Data + +1. **Receives the data** and validates the API token. +2. **Stores the raw payload** in: + +``` +INSTALL_PATH/log/plugins/last_result..encoded...log +``` + +* `` → plugin name from the POST request. +* `` → node name from the POST request. +* `` → incremented number for each submission. + +3. **Decodes / decrypts the data** if necessary (Base64 or encrypted) before processing. +4. **Processes JSON payloads** (e.g., device info) to: + + * Avoid duplicates by tracking `devMac`. + * Add metadata like `devSyncHubNode`. + * Insert new devices into the database. +5. **Renames files** to indicate they have been processed: + +``` +processed_last_result....log +``` + +--- + +### Example POST Payload + +If a node is sending device data: + +```bash +curl -X POST 'http://:/sync' \ -H 'Authorization: Bearer ' \ - -F 'data=' \ + -F 'data={"data":[{"devMac":"00:11:22:33:44:55","devName":"Device 1","devVendor":"Vendor A","devLastIP":"192.168.1.10"}]}' \ -F 'node_name=NODE-01' \ -F 'plugin=SYNC' ``` -**Response Example:** +* The `data` field contains JSON with a **`data` array**, where each element is a **device object** or **plugin data object**. +* The `plugin` and `node_name` fields allow the hub to **organize and store the file correctly**. -```json -{ - "message": "Data received and stored successfully" -} -``` +--- + +### Key Notes + +* **Always use the same `plugin` and `node_name` values** for consistent storage. +* **Encrypted data**: The Python script uses `encrypt_data()` before sending, and the hub decodes it before processing. +* **Sequence numbers**: Every submission generates a new sequence, preventing overwriting previous data. +* **Form-encoded**: The hub expects `multipart/form-data` (cURL `-F`) or `application/x-www-form-urlencoded`. **Storage Details:**