diff --git a/docs/server-api-v1/devices.md b/docs/server-api-v1/devices.md index ccfe489..d2f7f31 100644 --- a/docs/server-api-v1/devices.md +++ b/docs/server-api-v1/devices.md @@ -25,7 +25,7 @@ "connection_state": "active", // active | lost "last_contact": "2025-07-28 18:35", }, - ... + // ... ] } ``` @@ -47,7 +47,7 @@ "device_id": "ecf0a1b5c9d74f9a8e294c1f67b0a8b9", "device_ip": "192.168.1.42" }, - ... + // ... ] } ``` @@ -147,7 +147,7 @@ "id": 12, "alias": "...", "device_status": { - ... + // ... } } } @@ -162,7 +162,9 @@ ```json { "action": "action_name", - "params": {...} + "params": { + // ... + } } ``` @@ -175,7 +177,7 @@ "id": 12, "alias": "alias_name_like_variable", "response": { - ... + // ... } } } diff --git a/docs/server-api-v1/groups.md b/docs/server-api-v1/groups.md index 0383231..6c9f2fa 100644 --- a/docs/server-api-v1/groups.md +++ b/docs/server-api-v1/groups.md @@ -2,7 +2,7 @@ - В основном это нужно для назначения прав пользователям. - Группами пользователей может управлять только администратор или выше. -### Group STRUCT +### GROUP_STRUCT ```json { "id": 42, @@ -16,7 +16,7 @@ "access": "granted_at", // "granted" | "denied" | "granted_at" "granted_at": "05:00-18:30" // Если access = granted_at, то добавляется поле с указанием ренджа времени суток }, - ... + //... ], "update_at": "2025-07-29 19:45", "create_at": "2025-07-28 18:35" @@ -34,7 +34,8 @@ { "status": "ok", "groups": { - group_struct... + "GROUP_STRUCT" + // ... }, "total": 6 } @@ -68,7 +69,7 @@ ```json { "status": "ok", - "group": group_struct... + "group": "GROUP_STRUCT" } ``` @@ -98,7 +99,7 @@ ```json { "status": "ok", - "group": group_struct... + "group": "GROUP_STRUCT" } ``` @@ -125,7 +126,8 @@ { "status": "ok", "users": [ - user_struct... + "USER_STRUCT" + // ... ], "total": 11 } @@ -141,7 +143,7 @@ ```json { "status": "ok", - "user": user_struct... + "user": "USER_STRUCT" } ``` @@ -170,7 +172,7 @@ ```json { "status": "ok", - "group": group_struct... + "group": "GROUP_STRUCT" } ``` @@ -194,7 +196,7 @@ ```json { "status": "ok", - "group": group_struct... + "group": "GROUP_STRUCT" } ``` diff --git a/docs/server-api-v1/logs.md b/docs/server-api-v1/logs.md index 7fd4d34..7586235 100644 --- a/docs/server-api-v1/logs.md +++ b/docs/server-api-v1/logs.md @@ -6,27 +6,86 @@ **Доступно лишь администраторам и выше** +### LOG_ENTRY_STRUCT +```json + { + "id": 14, + "type": "user", // user | group | device | script | event | system | [custom_type] - (Для удобного поиска) + "user_id": 38, // Может отсутствовать + "group_alias": "some_group_alias", // Может отсутствовать + "device_id": 18, // Может отсутствовать + "script_alias": "script_alias", // Может отсутствовать + "event_name": "button_press", // может отсутствовать + "content": "Entry from log", // Обязательно должно что-то быть написано + "create_at": "2025-05-05 13:45:59" + } + ``` + --- ### POST `/api/v1/logs/new` -Добавить новую, кастомную запись в журнал +Добавить новую, кастомную запись в журнал. +- Для этого необходимо быть авторизированным +- Автоматически добавляемые поля: + - `user_id` авторизованного пользователя + - `group_alias` в которой состоит авторизованный пользователь + +#### Пример минимального запроса +```json + { + "type": "custom_type", + "content": "Information" + } + ``` --- ### GET `/api/v1/logs/list` Получить последние 50 записей в журнале +- **Доступно админу и выше** + +### Пример ответа +```json + { + "status": "ok", + "entries": [ + "LOG_ENTRY_STRUCT" + // ... + ], + "total": 1268 + } + ``` --- ### GET `/api/v1/logs/list/filtered` Получить фильтрованый, сортированый, порционный вывод записей. +- **Доступно админу и выше** **Аргументы:** - `by_user` - логи конкретного пользователя (ID) -- `by_group` - логи конкретной группы (ID) +- `by_group` - логи конкретной группы (alias) - `by_device` - логи конкретного девайса (ID) -- `by_script` - логи конкретного скрипта (ID) -- `by_event` - логи конкретного события (ID) +- `by_script` - логи конкретного скрипта (alias) +- `by_event` - логи конкретного события (название события) - `by_type` - Фильтр по конкретным типам записей (user, group, device, script, event, system ...) - `orderby` - Сортировать по указанному полю и порядок сортировки `field:ASC|DESC` - `from` - показать записи начиная с указаной, например с 100 (с сотой записи) -- `limit` - показать ограниченное количество записей, по умолчанию 50 \ No newline at end of file +- `limit` - показать ограниченное количество записей, по умолчанию 50 + +#### Пример запроса +- Вывести записи с 51 включительно по 100, группы `home`, типа `script`, сортированое по полю `id`, по убыванию. +`GET /api/v1/logs/list/filtered?by_group=home&by_type=script&orderby=id:DESC&from=51&limit=50` + +#### Пример положительного ответа +```json + { + "status": "ok", + "entries": [ + "LOG_ENTRY_STRUCT" + // ... + ], + "total": 168, + "from": 51, + "to": 100 + } + ``` \ No newline at end of file diff --git a/docs/server-api-v1/notifications.md b/docs/server-api-v1/notifications.md index 968c1a4..17b3be2 100644 --- a/docs/server-api-v1/notifications.md +++ b/docs/server-api-v1/notifications.md @@ -4,7 +4,7 @@ - Уведомления могут быть предназначены всем, отдельным группам пользователей или отдельным пользователям. Со стороны использования API это не играет роли. - Сторонними считаются уведомлениями сгенерированные скриптами или инициированные внешним источним через API -### Notification STRUCT +### NOTIFICATION_STRUCT ```json { "id": 42, @@ -27,9 +27,10 @@ ```json { "status": "ok", - "notifications": { - notification_struct... - }, + "notifications": [ + "NOTIFICATION_STRUCT" + // ... + ], "total": 10 } ``` @@ -43,7 +44,7 @@ ```json { "status": "ok", - "notification": notification_struct... + "notification": "NOTIFICATION_STRUCT" } ``` @@ -68,7 +69,7 @@ ```json { "status": "ok", - "notification": notification_struct... + "notification": "NOTIFICATION_STRUCT" } ``` diff --git a/docs/server-api-v1/scripts.md b/docs/server-api-v1/scripts.md index cc41541..c936695 100644 --- a/docs/server-api-v1/scripts.md +++ b/docs/server-api-v1/scripts.md @@ -1,36 +1,163 @@ ## Система скриптов - Все действия должны выполняться от имени авторизованого пользователя. -- Все скриптами может управлять только администратор. +- Cкриптами может управлять только администратор или выше. + +### SCRIPT_STRUCT +```json + { + "id": 11, + "alias": "bad_weather_light", + "filename": "bad_weather_light.php", + "path": "/home/smartserver/scripts", + "state": "enabled", // | disabled + "added_by": 12,// user_id + "created_by": "Eugene Sukhodolskiy", // Автор скрипта, брать будет из самого скрипта + "create_at": "2025-06-02 23:35:11" + } + ``` --- ### GET `/api/v1/scripts/list` Получить список скриптов +#### Пример ответа +```json + { + "status": "ok", + "scripts": [ + "SCRIPT_STRUCT" + // ... + ], + "total": 10 + } + ``` + --- ### GET `/api/v1/scripts/id/{{id}}` OR GET `/api/v1/scripts/alias/{{alias}}` Получить выбраный скрипт +#### Пример ответа +```json + { + "status": "ok", + "scripts": "SCRIPT_STRUCT" + } + ``` + --- ### POST `/api/v1/scripts/new` Зарегистрировать в системе новый скрипт +- По умолчанию, новый добавленый скрипт - не активен, имеет `state=disabled` + +#### Пример запроса +```json + { + "alias": "bad_weather_light", + "filename": "bad_weather_light.php", + "path": "/home/smartserver/scripts" + } + ``` + +### Пример НЕ успешного ответа. Невалидные поля +```json + { + "status": "error", + "field": "alias", + "message": "Alias already exists" // | "File not exists" + } + ``` --- ### POST `/api/v1/scripts/id/{{id}}/update` Редактировать скрипт +#### Пример запроса +```json + { + "alias": "bad_weather_light", + "filename": "bad_weather_light.php", + "path": "/home/smartserver/scripts", + "id": 11 // id существующего скрипта + } + ``` + +### Пример НЕ успешного ответа. Невалидные поля +```json + { + "status": "error", + "field": "alias", + "message": "Alias already exists" // | "File not exists" | "Script by id not found" + } + ``` + +--- + +### GET `/api/v1/scripts/id/{{id}}/enable` +Включить скрипт + +#### Пример ответа +```json + { + "status": "ok", + "scripts": "SCRIPT_STRUCT" + } + ``` + +--- + +### GET `/api/v1/scripts/id/{{id}}/disable` +Отключить скрипт + +#### Пример ответа +```json + { + "status": "ok", + "scripts": "SCRIPT_STRUCT" + } + ``` + --- ### GET `/api/v1/scripts/id/{{id}}/remove` Удалить скрипт из системы. (Сам скрипт при этом вполне может оставаться в файловой системе) +#### Пример ответа +```json + { + "status": "ok", + "scripts": "SCRIPT_STRUCT" + } + ``` + --- -### POST `/api/v1/scripts/id/{{id}}/run` +### POST `/api/v1/scripts/id/{{id}}/run` OR POST `/api/v1/scripts/alias/{{alias}}/run` Запустить выполнение скрипта. - При этом проверяется от имени какого пользователя был запущен скрипт. - Если прав пользователя не хватает - скрипт не запуститься. -- МОжно передать параметры, если скрипт этого ожидает. \ No newline at end of file +- Можно передать параметры, если скрипт этого ожидает. + +#### Пример запроса +```json + { + "params": { + // ... + } + } + ``` + +#### Пример ответа +```json + { + "status": "ok", + "script": "SCRIPT_STRUCT", + "result": { + // ... + } + } + ``` + diff --git a/docs/server-api-v1/users.md b/docs/server-api-v1/users.md index a8e47b4..f6db48e 100644 --- a/docs/server-api-v1/users.md +++ b/docs/server-api-v1/users.md @@ -2,7 +2,7 @@ - Пользователей может добавлять и удалять только супер админ. - Количество администраторов в системе не ограничено, однако супер админ может быть только один, это первый пользователь зарегистрированный в системе. -### USER STRUCT +### USER_STRUCT ```json { "id": 12, @@ -18,7 +18,7 @@ "viber": "+38063xxxxxxx", }, "role": "user", - "group": group_struct... , // | false + "group": "GROUP_STRUCT", // | false "last_activity": "2025-07-28 18:35", "create_at": "2025-07-28 18:35" } @@ -47,7 +47,7 @@ ```json { "status": "ok", - "user": user_struct... + "user": "USER_STRUCT" } ``` @@ -78,7 +78,8 @@ { "status": "ok", "users": [ - user_struct... + "USER_STRUCT" + // ... ], "total": 15 } @@ -101,7 +102,7 @@ ```json { "status": "ok", - "user": user_struct... + "user": "USER_STRUCT" } ``` @@ -122,7 +123,7 @@ ```json { "status": "ok", - "user": user_struct... + "user": "USER_STRUCT" } ``` @@ -144,7 +145,7 @@ ```json { "status": "ok", - "user": user_struct... + "user": "USER_STRUCT" } ``` @@ -165,7 +166,7 @@ ```json { "status": "ok", - "user": user_struct... + "user": "USER_STRUCT" } ``` @@ -276,7 +277,7 @@ ```json { "status": "ok", - "user": user_struct... + "user": "USER_STRUCT" } ```