Areas REST API (v1)

Назначение: управление физическими областями (Areas), а не абстрактными пространствами (Spaces).

AREA_STRUCT (пример)

    {
        "id": 2,
        "type": "room",
        "alias": "kitchen",
        "display_name": "Кухня",
        "parent_area_id": 0
    }

GET /api/v1/areas/list

Получить список всех областей в системе

Пример ответа

    {
        "status": true,
        "data": {
            "areas": [
                {
                    "id": 2,
                    "type": "room",
                    "alias": "kitchen",
                    "display_name": "Кухня"
                }
            ],
            "total": 1
        }
    }

GET /api/v1/areas/id/{{area_id}}/list

Получить список вложенных областей указанной области (child areas).

Пример успешного ответа

    {
        "status": true,
        "data": {
            "areas": [
                {
                    "id": 5,
                    "type": "room",
                    "alias": "bedroom",
                    "display_name": "Спальня"
                }
            ],
            "total": 1
        }
    }

Возможные ошибки

    {
        "status": false,
        "error_alias": "parent_area_not_found"
    }

POST /api/v1/areas/new-area

Добавить новую физическую область.

Пример запроса

    {
        "type": "room",
        "alias": "kitchen",
        "display_name": "Кухня"
    }

Пример успешного ответа

    {
        "status": true,
        "data": {
            "alias": "kitchen",
            "area": {
                "id": 2,
                "type": "room",
                "alias": "kitchen",
                "display_name": "Кухня"
            }
        }
    }

Пример НЕ успешного ответа

    {
        "status": false,
        "error_alias": "alias_already_exists", // empty_field | area_not_exists
        "failed_fields": ["alias"] // display_name, type
    }

GET /api/v1/areas/id/{{area_id}}/remove

Удалить область.

Поведение:

• область удаляется из системы
• все устройства и child-области, которые были в ней, будут отвязаны (логика внутри Area::remove()) Ограничения:
• area_id должен быть числом > 1 (id=1 и ниже — запрещено)

Пример успешного ответа

    {
        "status": true
    }

Пример НЕ успешного ответа

    {
        "status": false,
        "error_alias": "invalid_id", // area_not_exists | undefined_error
        "failed_fields": ["area_id"]
    }

POST /api/v1/areas/place-in-area

Поместить одну область в другую (сделать вложенной).

Пример запроса

    {
        "target_area_id": 5,
        "place_in_area_id": 2
    }

Пример успешного ответа

    {
        "status": true
    }

Пример НЕ успешного ответа

    {
        "status": false,
        "error_alias": "invalid_id", // area_not_exists | undefined_error
        "failed_fields": ["target_area_id"] // place_in_area_id
    }

POST /api/v1/areas/update-display-name

Переименовать область (изменить display_name).

Пример запроса

    {
        "area_id": 2,
        "display_name": "Кухня (1 этаж)"
    }

Пример успешного ответа

    {
        "status": true,
        "data": {
            "alias": "kitchen",
            "area": {
                "id": 2,
                "type": "room",
                "alias": "kitchen",
                "display_name": "Кухня (1 этаж)"
            }
        }
    }

Пример НЕ успешного ответа

    {
        "status": false,
        "error_alias": "invalid_id", // empty_field | area_not_exists | undefined_error
        "failed_fields": ["display_name"]
    }

POST /api/v1/areas/update-alias

Изменить alias области. Предупреждение: если alias используется в скриптах — это может сломать скрипты.

Пример запроса

    {
        "area_id": 2,
        "new_alias": "kitchen_floor_1"
    }

Пример успешного ответа

    {
        "status": true,
        "data": {
            "alias": "kitchen_floor_1",
            "area": {
                "id": 2,
                "type": "room",
                "alias": "kitchen_floor_1",
                "display_name": "Кухня"
            }
        }
    }

Пример НЕ успешного ответа

    {
        "status": false,
        "error_alias": "invalid_id", // empty_field | alias_already_exists | area_not_exists | undefined_error
        "failed_fields": ["area_id"] // new_alias, alias, 
    }

GET /api/v1/areas/id/{{area_id}}/devices

Получить список устройств, помещённых в область (включая вложенные области), т.к. вызывается get_inner_devices(true).

Пример ответа

    {
        "status": true,
        "data": {
            "devices": [
                {
                    "id": 12,
                    "alias": "pump_relay",
                    "name": "Реле помпы септика"
                }
            ],
            "total": 1
        }
    }

Пример НЕ успешного ответа

    {
        "status": false,
        "error_alias": "invalid_id", // area_not_exists
        "failed_fields": ["area_id"]
    }

GET /api/v1/areas/id/{{area_id}}/unassign-from-area

Отвязать область от родительской области (сделать её верхнеуровневой). Устройства внутри области остаются. Ограничение: area_id должен быть числом > 1.

Пример успешного ответа

    {
        "status": true
    }

Пример НЕ успешного ответа

    {
        "status": false,
        "error_alias": "invalid_id", // area_not_exists | undefined_error
        "failed_fields": ["area_id"]
    }

GET /api/v1/areas/reboot_devices OR GET /api/v1/areas/id/{{area_id}}/reboot_devices

Перезагрузить все устройства, или все устройства находящиеся в указанной области (и вложенных областях)

Пример успешного ответа

    {
        "status": true,
        "data": {
            "results": {
                "kitchen:pump_relay": {
                    "status": true
                }
            },
            "total": 1
        }
    }

Пример НЕ успешного ответа

    {
        "status": false,
        "error_alias": "area_not_exists"
    }

GET /api/v1/areas/types/list

Получить список существующих пользовательских типов областей из БД.

Пример ответа

    {
        "status": true,
        "data": {
            "types": ["room", "floor", "building"]
        }
    }