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

---
#### AREA_STRUCT (пример)
```json
	{
		"id": 2,
		"type": "room",
		"alias": "kitchen",
		"display_name": "Кухня",
		"parent_area_id": 0
	}
```

---

### GET `/api/v1/areas/list`
Получить список всех областей в системе

#### Пример ответа
```json
	{
		"status": true,
		"data": {
			"areas": [
				{
					"id": 2,
					"type": "room",
					"alias": "kitchen",
					"display_name": "Кухня"
				}
			],
			"total": 1
		}
	}
```

---

### GET `/api/v1/areas/id/{{area_id}}/list`
Получить список вложенных областей указанной области (child areas).

#### Пример успешного ответа
```json 
	{
		"status": true,
		"data": {
			"areas": [
				{
					"id": 5,
					"type": "room",
					"alias": "bedroom",
					"display_name": "Спальня"
				}
			],
			"total": 1
		}
	}
```

#### Возможные ошибки
```json
	{
		"status": false,
		"error_alias": "parent_area_not_found"
	}
```

---

### POST `/api/v1/areas/new-area`
Добавить новую физическую область.

#### Пример запроса
```json
	{
		"type": "room",
		"alias": "kitchen",
		"display_name": "Кухня"
	}
```

#### Пример успешного ответа
```json
	{
		"status": true,
		"data": {
			"alias": "kitchen",
			"area": {
				"id": 2,
				"type": "room",
				"alias": "kitchen",
				"display_name": "Кухня"
			}
		}
	}
```

#### Пример НЕ успешного ответа
```json
	{
		"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 и ниже — запрещено)

#### Пример успешного ответа
```json
	{
		"status": true
	}
```

#### Пример НЕ успешного ответа
```json
	{
		"status": false,
		"error_alias": "invalid_id", // area_not_exists | undefined_error
		"failed_fields": ["area_id"]
	}
```

---

### POST `/api/v1/areas/place-in-area`
Поместить одну область в другую (сделать вложенной).

##### Пример запроса
```json
	{
		"target_area_id": 5,
		"place_in_area_id": 2
	}
```

#### Пример успешного ответа
```json
	{
		"status": true
	}
```

#### Пример НЕ успешного ответа
```json
	{
		"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).

#### Пример запроса
```json
	{
		"area_id": 2,
		"display_name": "Кухня (1 этаж)"
	}
```

#### Пример успешного ответа
```json
	{
		"status": true,
		"data": {
			"alias": "kitchen",
			"area": {
				"id": 2,
				"type": "room",
				"alias": "kitchen",
				"display_name": "Кухня (1 этаж)"
			}
		}
	}
```

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

```json
	{
		"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 используется в скриптах — это может сломать скрипты.

#### Пример запроса
```json
	{
		"area_id": 2,
		"new_alias": "kitchen_floor_1"
	}
```

#### Пример успешного ответа
```json
	{
		"status": true,
		"data": {
			"alias": "kitchen_floor_1",
			"area": {
				"id": 2,
				"type": "room",
				"alias": "kitchen_floor_1",
				"display_name": "Кухня"
			}
		}
	}
```

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

```json
	{
		"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).

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

#### Пример НЕ успешного ответа
```json
	{
		"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.

#### Пример успешного ответа
```json
	{
		"status": true
	}
```

#### Пример НЕ успешного ответа
```json
	{
		"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`
Перезагрузить все устройства, или все устройства находящиеся в указанной области (и вложенных областях)

### Пример успешного ответа
```json
	{
		"status": true,
		"data": {
			"results": {
				"kitchen:pump_relay": {
					"status": true
				}
			},
			"total": 1
		}
	}
```

#### Пример НЕ успешного ответа
```json
	{
		"status": false,
		"error_alias": "area_not_exists"
	}
```

---

### GET `/api/v1/areas/types/list`
Получить список существующих пользовательских типов областей из БД.

#### Пример ответа
```json
	{
		"status": true,
		"data": {
			"types": ["room", "floor", "building"]
		}
	}
```
