vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2025-12-06 17:15:38 -08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
jokob-sk
2025-08-25 18:19:02 +10:00
parent 40e9fbdb3f
commit ce887968b7
4 changed files with 126 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/API.md
View File

@@ -1,6 +1,6 @@
# NetAlertX API Documentation
This API provides programmatic access to **devices, events, sessions, metrics, network tools, and sync** in NetAlertX. It is implemented as a **REST and GraphQL server**. All requests require authentication via **API Token** (`API_TOKEN` setting) unless explicitly noted.
This API provides programmatic access to **devices, events, sessions, metrics, network tools, and sync** in NetAlertX. It is implemented as a **REST and GraphQL server**. All requests require authentication via **API Token** (`API_TOKEN` setting) unless explicitly noted. For example, to authorize a GraphQL request, you need to use a `Authorization: Bearer API_TOKEN` header as per example below:
```graphql
curl 'http://host:GRAPHQL_PORT/graphql' \
@@ -21,7 +21,7 @@ curl 'http://host:GRAPHQL_PORT/graphql' \
}'
```
It runs on `0.0.0.0:<graphql_port>` with **CORS enabled** for all main endpoints.
The API server runs on `0.0.0.0:<graphql_port>` with **CORS enabled** for all main endpoints.
---
@@ -51,9 +51,8 @@ http://<server>:<GRAPHQL_PORT>/
## Endpoints
> [!TIP]
> When retrieving devices try using the GraphQL API endpoint first as it is read-optimized.
> When retrieving devices or settings 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
@@ -76,5 +75,3 @@ See [Testing](API_TESTS.md) for example requests and usage.
* GraphQL is available for advanced queries, while REST endpoints cover structured use cases.
* Endpoints run on `0.0.0.0:<GRAPHQL_PORT>` with **CORS enabled**.
* Use consistent API tokens and node/plugin names when interacting with `/sync` to ensure data integrity.

152
docs/API_GRAPHQL.md
View File

@@ -1,6 +1,9 @@
# GraphQL API Endpoint
GraphQL queries are read-optimized for speed. Data may be slightly out of date until the file system cache refreshes.
GraphQL queries are **read-optimized for speed**. Data may be slightly out of date until the file system cache refreshes. The GraphQL endpoints allows you to access the following objects:
- Devices
- Settings
## Endpoints
@@ -12,7 +15,9 @@ GraphQL queries are read-optimized for speed. Data may be slightly out of date u
---
## Sample Query
## Devices Query
### Sample Query
```graphql
query GetDevices($options: PageQueryOptionsInput) {
@@ -32,11 +37,20 @@ query GetDevices($options: PageQueryOptionsInput) {
}
```
See also: [Debugging GraphQL issues](./DEBUG_GRAPHQL.md)
### Query Parameters
| Parameter | Description |
| --------- | ------------------------------------------------------------------------------------------------------- |
| `page` | Page number of results to fetch. |
| `limit` | Number of results per page. |
| `sort` | Sorting options (`field` = field name, `order` = `asc` or `desc`). |
| `search` | Term to filter devices. |
| `status` | Filter devices by status: `my_devices`, `connected`, `favorites`, `new`, `down`, `archived`, `offline`. |
| `filters` | Additional filters (array of `{ filterColumn, filterValue }`). |
---
## `curl` Example
### `curl` Example
```sh
curl 'http://host:GRAPHQL_PORT/graphql' \
@@ -59,27 +73,7 @@ curl 'http://host:GRAPHQL_PORT/graphql' \
---
## Query Parameters
| Parameter | Description |
| --------- | ------------------------------------------------------------------------------------------------------- |
| `page` | Page number of results to fetch. |
| `limit` | Number of results per page. |
| `sort` | Sorting options (`field` = field name, `order` = `asc` or `desc`). |
| `search` | Term to filter devices. |
| `status` | Filter devices by status: `my_devices`, `connected`, `favorites`, `new`, `down`, `archived`, `offline`. |
---
## Notes on `curl`
* `-X POST` specifies a POST request.
* `-H 'Content-Type: application/json'` sets JSON content type.
* `--data` provides the request payload (GraphQL query + variables).
---
## Sample Response
### Sample Response
```json
{
@@ -95,16 +89,99 @@ curl 'http://host:GRAPHQL_PORT/graphql' \
"devVendor": "Vendor 1",
"devLastConnection": "2025-01-01T00:00:00Z",
"devStatus": "connected"
}
],
"count": 1
}
}
}
```
---
## Settings Query
The **settings query** provides access to NetAlertX configuration stored in the settings table.
### Sample Query
```graphql
query GetSettings {
settings {
settings {
setKey
setName
setDescription
setType
setOptions
setGroup
setValue
setEvents
setOverriddenByEnv
}
count
}
}
```
### Schema Fields
| Field | Type | Description |
| -------------------- | ------- | ------------------------------------------------------------------------ |
| `setKey` | String | Unique key identifier for the setting. |
| `setName` | String | Human-readable name. |
| `setDescription` | String | Description or documentation of the setting. |
| `setType` | String | Data type (`string`, `int`, `bool`, `json`, etc.). |
| `setOptions` | String | Available options (for dropdown/select-type settings). |
| `setGroup` | String | Group/category the setting belongs to. |
| `setValue` | String | Current value of the setting. |
| `setEvents` | String | Events or triggers related to this setting. |
| `setOverriddenByEnv` | Boolean | Whether the setting is overridden by an environment variable at runtime. |
---
### `curl` Example
```sh
curl 'http://host: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 } }"
}'
```
---
### Sample Response
```json
{
"data": {
"settings": {
"settings": [
{
"setKey": "UI_MY_DEVICES",
"setName": "My Devices Filter",
"setDescription": "Defines which statuses to include in the 'My Devices' view.",
"setType": "list",
"setOptions": "[\"online\",\"new\",\"down\",\"offline\",\"archived\"]",
"setGroup": "UI",
"setValue": "[\"online\",\"new\"]",
"setEvents": null,
"setOverriddenByEnv": false
},
{
"rowid": 2,
"devMac": "66:77:88:99:AA:BB",
"devName": "Device 2",
"devOwner": "Owner 2",
"devType": "Type 2",
"devVendor": "Vendor 2",
"devLastConnection": "2025-01-02T00:00:00Z",
"devStatus": "connected"
"setKey": "NETWORK_DEVICE_TYPES",
"setName": "Network Device Types",
"setDescription": "Types of devices considered as network infrastructure.",
"setType": "list",
"setOptions": "[\"Router\",\"Switch\",\"AP\"]",
"setGroup": "Network",
"setValue": "[\"Router\",\"Switch\"]",
"setEvents": null,
"setOverriddenByEnv": true
}
],
"count": 2
@@ -112,3 +189,12 @@ curl 'http://host:GRAPHQL_PORT/graphql' \
}
}
```
---
## Notes
* Device and settings queries can be combined in one request since GraphQL supports batching.
* The `setOverriddenByEnv` flag helps identify setting values that are locked at container runtime.
* The schema is **read-only** — updates must be performed through other APIs or configuration management. See the other [API](API.md) endpoints for details.

4
docs/API_OLD.md
View File

@@ -1,6 +1,6 @@
# API endpoints
# [Deprecated] API endpoints
> [!NOTE]
> [!WARNING]
> Some of these endpoints will be deprecated soon. Please refere to the new [API](API.md) endpoints docs for details on the new API layer.
NetAlertX comes with a couple of API endpoints. All requests need to be authorized (executed in a logged in browser session) or you have to pass the value of the `API_TOKEN` settings as authorization bearer, for example:

2
docs/API_SYNC.md
View File

@@ -91,6 +91,7 @@ curl -X POST 'http://<hub>:<PORT>/sync' \
* 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**.
* The data is only processed if the relevant plugins are enabled and run on the target server.
---
@@ -111,6 +112,7 @@ last_result.<plugin>.encoded.<node_name>.<sequence>.log
* Both encoded and decoded files are tracked, and new submissions increment the sequence number.
* If storing fails, the API returns HTTP 500 with an error message.
* The data is only processed if the relevant plugins are enabled and run on the target server.
---