From 6f606f34d11d0ddd97bdb90f5efde8a87178d37f Mon Sep 17 00:00:00 2001 From: jokob-sk Date: Sun, 31 Aug 2025 10:23:31 +1000 Subject: [PATCH] docs Signed-off-by: jokob-sk --- docs/API.md | 1 + docs/API_DBQUERY.md | 60 +++++++++++++++++++++++----- docs/API_SESSIONS.md | 59 +++++++++++++++++++++++++++ docs/API_SETTINGS.md | 92 +++++++++++++++++++++++++++++++++++++++++++ docs/DEV_ENV_SETUP.md | 14 +------ mkdocs.yml | 3 +- 6 files changed, 207 insertions(+), 22 deletions(-) create mode 100755 docs/API_SETTINGS.md diff --git a/docs/API.md b/docs/API.md index 97486102..aedda20b 100755 --- a/docs/API.md +++ b/docs/API.md @@ -58,6 +58,7 @@ http://:/ * [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 diff --git a/docs/API_DBQUERY.md b/docs/API_DBQUERY.md index 05c2ae4a..a896d1c7 100755 --- a/docs/API_DBQUERY.md +++ b/docs/API_DBQUERY.md @@ -55,6 +55,18 @@ SELECT * FROM Devices; } ``` +#### `curl` Example + +```bash +curl -X POST "http://:/dbquery/read" \ + -H "Authorization: Bearer " \ + -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://:/dbquery/update" \ + -H "Authorization: Bearer " \ + -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://:/dbquery/write" \ + -H "Authorization: Bearer " \ + -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://:/dbquery/delete" \ + -H "Authorization: Bearer " \ + -H "Accept: application/json" \ + -H "Content-Type: application/json" \ + -d '{ + "columnName": "devMac", + "id": ["AA:BB:CC:DD:EE:FF"], + "dbtable": "Devices" + }' +``` diff --git a/docs/API_SESSIONS.md b/docs/API_SESSIONS.md index a9412120..e5a4e746 100755 --- 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://:/sessions/create" \ + -H "Authorization: Bearer " \ + -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://:/sessions/delete" \ + -H "Authorization: Bearer " \ + -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://:/sessions/list?mac=AA:BB:CC:DD:EE:FF&start_date=2025-08-01&end_date=2025-08-21" \ + -H "Authorization: Bearer " \ + -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://:/sessions/calendar?start=2025-08-01&end=2025-08-21" \ + -H "Authorization: Bearer " \ + -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://:/sessions/AA:BB:CC:DD:EE:FF?period=7%20days" \ + -H "Authorization: Bearer " \ + -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://:/sessions/session-events?type=all&period=7%20days" \ + -H "Authorization: Bearer " \ + -H "Accept: application/json" +``` \ No newline at end of file diff --git a/docs/API_SETTINGS.md b/docs/API_SETTINGS.md new file mode 100755 index 00000000..27078b01 --- /dev/null +++ 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/` → 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://:/settings/API_TOKEN' \ + -H 'Authorization: Bearer ' \ + -H 'Accept: application/json' +``` + +**Response:** + +```json +{ + "success": true, + "value": "my-secret-token" +} +``` + +--- + +#### `curl` Example (Invalid Key) + +```sh +curl 'http://:/settings/DOES_NOT_EXIST' \ + -H 'Authorization: Bearer ' \ + -H 'Accept: application/json' +``` + +**Response:** + +```json +{ + "success": true, + "value": null +} +``` + +--- + +#### `curl` Example (Unauthorized) + +```sh +curl 'http://:/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://:/graphql' \ + -X POST \ + -H 'Authorization: Bearer ' \ + -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. diff --git a/docs/DEV_ENV_SETUP.md b/docs/DEV_ENV_SETUP.md index 13640e0a..175bfdfc 100755 --- 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). \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 80c5b867..41338c66 100755 --- 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