docs

Signed-off-by: jokob-sk <jokob.sk@gmail.com>
2025-12-06 17:15:38 -08:00 · 2025-08-31 10:23:31 +10:00
parent fd3f1fc929
commit 6f606f34d1
6 changed files with 207 additions and 22 deletions
--- a/docs/API.md
+++ b/docs/API.md
@@ -58,6 +58,7 @@ http://<server>:<GRAPHQL_PORT>/
 * [Devices Collection](API_DEVICES.md) – Bulk operations on multiple devices
 * [Events](API_EVENTS.md) – Device event logging and management
 * [Sessions](API_SESSIONS.md) – Connection sessions and history
+* [Settings](API_SETTINGS.md) – Settings
 * [Metrics](API_METRICS.md) – Prometheus metrics and per-device status
 * [Network Tools](API_NETTOOLS.md) – Utilities like Wake-on-LAN, traceroute, nslookup, nmap, and internet info
 * [Online History](API_ONLINEHISTORY.md) – Online/offline device records
--- a/docs/API_DBQUERY.md
+++ b/docs/API_DBQUERY.md
@@ -55,6 +55,18 @@ SELECT * FROM Devices;
 }
 ```

+#### `curl` Example
+
+```bash
+curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/dbquery/read" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Accept: application/json" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "rawSql": "U0VMRUNUICogRlJPTSBERVZJQ0VT"
+  }'
+```
+
 ---

 ### 2. `POST /dbquery/update` (safer than `/dbquery/write`)
@@ -79,6 +91,22 @@ Update rows in a table by `columnName` + `id`. `/dbquery/update` is parameterize
 { "success": true, "updated_count": 1 }
 ```

+#### `curl` Example
+
+```bash
+curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/dbquery/update" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Accept: application/json" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "columnName": "devMac",
+    "id": ["AA:BB:CC:DD:EE:FF"],
+    "dbtable": "Devices",
+    "columns": ["devName", "devOwner"],
+    "values": ["Laptop", "Alice"]
+  }'
+```
+
 ---

 ### 3. `POST /dbquery/write`
@@ -91,7 +119,6 @@ Execute a **write query** (`INSERT`, `UPDATE`, `DELETE`).
 {
  "rawSql": "SU5TRVJUIElOVE8gRGV2aWNlcyAoZGV2TWFjLCBkZXYgTmFtZSwgZGV2Rmlyc3RDb25uZWN0aW9uLCBkZXZMYXN0Q29ubmVjdGlvbiwgZGV2TGFzdElQKSBWQUxVRVMgKCc2QTpCQjo0Qzo1RDo2RTonLCAnVGVzdERldmljZScsICcyMDI1LTA4LTMwIDEyOjAwOjAwJywgJzIwMjUtMDgtMzAgMTI6MDA6MDAnLCAnMTAuMC4wLjEwJyk="
 }
-
 ```

 Decoded SQL:
@@ -99,7 +126,6 @@ Decoded SQL:
 ```sql
 INSERT INTO Devices (devMac, devName, devFirstConnection, devLastConnection, devLastIP)
 VALUES ('6A:BB:4C:5D:6E', 'TestDevice', '2025-08-30 12:00:00', '2025-08-30 12:00:00', '10.0.0.10');
-
 ```

 #### Response
@@ -108,6 +134,17 @@ VALUES ('6A:BB:4C:5D:6E', 'TestDevice', '2025-08-30 12:00:00', '2025-08-30 12:00
 { "success": true, "affected_rows": 1 }
 ```

+#### `curl` Example
+
+```bash
+curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/dbquery/write" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Accept: application/json" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "rawSql": "SU5TRVJUIElOVE8gRGV2aWNlcyAoZGV2TWFjLCBkZXYgTmFtZSwgZGV2Rmlyc3RDb25uZWN0aW9uLCBkZXZMYXN0Q29ubmVjdGlvbiwgZGV2TGFzdElQKSBWQUxVRVMgKCc2QTpCQjo0Qzo1RDo2RTonLCAnVGVzdERldmljZScsICcyMDI1LTA4LTMwIDEyOjAwOjAwJywgJzIwMjUtMDgtMzAgMTI6MDA6MDAnLCAnMTAuMC4wLjEwJyk="
+  }'
+```

 ---

@@ -131,11 +168,16 @@ Delete rows in a table by `columnName` + `id`.
 { "success": true, "deleted_count": 1 }
 ```

---
+#### `curl` Example

-## Notes & Best Practices
-
-* All queries must be **base64 encoded** when passed as `rawSql`.
-* `update` and `delete` endpoints use **structured parameters** to prevent SQL injection.
-* Avoid large or complex queries in `read` — paginate results instead.
-* Always validate queries in a safe environment before running them via API.
+```bash
+curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/dbquery/delete" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Accept: application/json" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "columnName": "devMac",
+    "id": ["AA:BB:CC:DD:EE:FF"],
+    "dbtable": "Devices"
+  }'
+```
--- a/docs/API_SESSIONS.md
+++ b/docs/API_SESSIONS.md
@@ -28,6 +28,24 @@ Track and manage device connection sessions. Sessions record when a device conne
  }
  ```

+#### `curl` Example
+
+```bash
+curl -X POST "http://<server_ip>:<GRAPHQL_PORT>/sessions/create" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Accept: application/json" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "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",
+    "event_type_conn": "Connected",
+    "event_type_disc": "Disconnected"
+  }'
+
+```
+
 ---

 ### Delete Sessions
@@ -51,6 +69,18 @@ Track and manage device connection sessions. Sessions record when a device conne
  }
  ```

+#### `curl` Example
+
+```bash
+curl -X DELETE "http://<server_ip>:<GRAPHQL_PORT>/sessions/delete" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Accept: application/json" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "mac": "AA:BB:CC:DD:EE:FF"
+  }'
+```
+
 ---

 ### List Sessions
@@ -86,7 +116,13 @@ Track and manage device connection sessions. Sessions record when a device conne
    ]
  }
  ```
+#### `curl` Example

+```bash
+curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/sessions/list?mac=AA:BB:CC:DD:EE:FF&start_date=2025-08-01&end_date=2025-08-21" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Accept: application/json"
+```
 ---

 ### Calendar View of Sessions
@@ -123,6 +159,14 @@ Track and manage device connection sessions. Sessions record when a device conne
  }
  ```

+#### `curl` Example
+
+```bash
+curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/sessions/calendar?start=2025-08-01&end=2025-08-21" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Accept: application/json"
+```
+
 ---

 ### Device Sessions
@@ -158,6 +202,14 @@ Track and manage device connection sessions. Sessions record when a device conne
  }
  ```

+#### `curl` Example
+
+```bash
+curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/sessions/AA:BB:CC:DD:EE:FF?period=7%20days" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Accept: application/json"
+```
+
 ---

 ### Session Events Summary
@@ -179,3 +231,10 @@ Track and manage device connection sessions. Sessions record when a device conne
  **Response:**
  Returns a list of events or sessions with formatted connection, disconnection, duration, and IP information.

+#### `curl` Example
+
+```bash
+curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/sessions/session-events?type=all&period=7%20days" \
+  -H "Authorization: Bearer <API_TOKEN>" \
+  -H "Accept: application/json"
+```
--- a/docs/API_SETTINGS.md
+++ b/docs/API_SETTINGS.md
@@ -0,0 +1,92 @@
+# Settings API Endpoints
+
+Retrieve application settings stored in the configuration system. This endpoint is useful for quickly fetching individual settings such as `API_TOKEN` or `TIMEZONE`.
+
+For bulk or structured access (all settings, schema details, or filtering), use the [GraphQL API Endpoint](API_GRAPHQL.md).
+
+---
+
+### Get a Setting
+
+* **GET** `/settings/<key>` → Retrieve the value of a specific setting
+
+**Path Parameter:**
+
+* `key` → The setting key to retrieve (e.g., `API_TOKEN`, `TIMEZONE`)
+
+**Authorization:**
+Requires a valid API token in the `Authorization` header.
+
+---
+
+#### `curl` Example (Success)
+
+```sh
+curl 'http://<server_ip>:<GRAPHQL_PORT>/settings/API_TOKEN' \
+  -H 'Authorization: Bearer <API_TOKEN>' \
+  -H 'Accept: application/json'
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "value": "my-secret-token"
+}
+```
+
+---
+
+#### `curl` Example (Invalid Key)
+
+```sh
+curl 'http://<server_ip>:<GRAPHQL_PORT>/settings/DOES_NOT_EXIST' \
+  -H 'Authorization: Bearer <API_TOKEN>' \
+  -H 'Accept: application/json'
+```
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "value": null
+}
+```
+
+---
+
+#### `curl` Example (Unauthorized)
+
+```sh
+curl 'http://<server_ip>:<GRAPHQL_PORT>/settings/API_TOKEN' \
+  -H 'Accept: application/json'
+```
+
+**Response:**
+
+```json
+{
+  "error": "Forbidden"
+}
+```
+
+---
+
+### Notes
+
+* This endpoint is optimized for **direct retrieval of a single setting**.
+* For **complex retrieval scenarios** (listing all settings, retrieving schema metadata like `setName`, `setDescription`, `setType`, or checking if a setting is overridden by environment variables), use the **GraphQL Settings Query**:
+
+```sh
+curl 'http://<server_ip>:<GRAPHQL_PORT>/graphql' \
+  -X POST \
+  -H 'Authorization: Bearer <API_TOKEN>' \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "query": "query GetSettings { settings { settings { setKey setName setDescription setType setOptions setGroup setValue setEvents setOverriddenByEnv } count } }"
+  }'
+```
+
+See the [GraphQL API Endpoint](API_GRAPHQL.md) for more details.
--- a/docs/DEV_ENV_SETUP.md
+++ b/docs/DEV_ENV_SETUP.md
@@ -130,15 +130,5 @@ Most code changes can be tested without rebuilding the container. When working o
 - Plugin functionality.
 - Error log inspection.

-### Unit Tests
-
->[!WARNING]
-> Please note these test modify data in the database. 
-
-1. See the `/test` directory for available test cases. These are not exhaustive but cover the main API endpoints.  
-2. To run a test case, SSH into the container:  
-   `sudo docker exec -it netalertx /bin/bash`  
-3. Inside the container, install pytest (if not already installed):  
-   `pip install pytest`  
-4. Run a specific test case:  
-   `pytest /app/test/TESTFILE.py`
+> [!NOTE]  
+> Always run all available tests as per the [Testing documentation](API_TESTS.md).
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -79,10 +79,10 @@ nav:
        - Icon and Type guessing: DEVICE_HEURISTICS.md
      - API: 
        - Overview: API.md   
-        - OLD API Overview: API_OLD.md   
        - Devices Collection: API_DEVICES.md
        - Device: API_DEVICE.md
        - Sessions: API_SESSIONS.md
+        - Settings: API_SETTINGS.md
        - Events: API_EVENTS.md
        - Metrics: API_METRICS.md
        - Net Tools: API_NETTOOLS.md
@@ -91,6 +91,7 @@ nav:
        - GraphQL: API_GRAPHQL.md
        - DB query: API_DBQUERY.md
        - Tests: API_TESTS.md
+        - SUPERSEDED OLD API Overview: API_OLD.md   
      - Integrations:
        - Webhook Secret: WEBHOOK_SECRET.md            
        - Helper scripts: HELPER_SCRIPTS.md