diff --git a/docs/API.md b/docs/API.md index f5f5ba3f..ea5a6aa4 100755 --- a/docs/API.md +++ b/docs/API.md @@ -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:` with **CORS enabled** for all main endpoints. +The API server runs on `0.0.0.0:` with **CORS enabled** for all main endpoints. --- @@ -51,9 +51,8 @@ http://:/ ## 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:` with **CORS enabled**. * Use consistent API tokens and node/plugin names when interacting with `/sync` to ensure data integrity. - - diff --git a/docs/API_GRAPHQL.md b/docs/API_GRAPHQL.md index be784d66..d3016b1e 100755 --- a/docs/API_GRAPHQL.md +++ b/docs/API_GRAPHQL.md @@ -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. + diff --git a/docs/API_OLD.md b/docs/API_OLD.md index 19457614..6d1f21fb 100755 --- a/docs/API_OLD.md +++ b/docs/API_OLD.md @@ -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: diff --git a/docs/API_SYNC.md b/docs/API_SYNC.md index 096f6bf8..c7569170 100755 --- a/docs/API_SYNC.md +++ b/docs/API_SYNC.md @@ -91,6 +91,7 @@ curl -X POST 'http://:/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..encoded...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. ---