mirror of
https://github.com/jokob-sk/NetAlertX.git
synced 2025-12-06 17:15:38 -08:00
docs
This commit is contained in:
jokob-sk
@@ -51,6 +51,10 @@ http://<server>:<GRAPHQL_PORT>/
|
||||
|
||||
## 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
|
||||
|
||||
@@ -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> days"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@@ -30,30 +30,3 @@ Manage the **online history records** of devices. Currently, the API supports de
|
||||
curl -X DELETE "http://<server_ip>:<GRAPHQL_PORT>/history" \
|
||||
-H "Authorization: Bearer <API_TOKEN>"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 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.
|
||||
|
||||
@@ -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=<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/<mac>?period=1 day` → Sessions for a device
|
||||
* **GET** `/sessions/session-events?type=all&period=7 days` → Session events summary
|
||||
|
||||
---
|
||||
|
||||
### 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/<mac>` → 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.
|
||||
|
||||
|
||||
@@ -37,33 +37,69 @@ curl 'http://<server>:<GRAPHQL_PORT>/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.<plugin>...`). |
|
||||
| `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://<server>:<GRAPHQL_PORT>/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.<plugin>.encoded.<node_name>.<sequence>.log
|
||||
```
|
||||
|
||||
* `<plugin>` → plugin name from the POST request.
|
||||
* `<node_name>` → node name from the POST request.
|
||||
* `<sequence>` → 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.<plugin>.<node_name>.<sequence>.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example POST Payload
|
||||
|
||||
If a node is sending device data:
|
||||
|
||||
```bash
|
||||
curl -X POST 'http://<hub>:<PORT>/sync' \
|
||||
-H 'Authorization: Bearer <API_TOKEN>' \
|
||||
-F 'data=<payload here>' \
|
||||
-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:**
|
||||
|
||||
|
||||
Reference in New Issue
Block a user