Спецификация REST API для устройств умного дома на ESP

Общие положения

• Транспорт: HTTP, формат данных — JSON.
• Архитектура: Каждый тип устройства реализует базовые эндпоинты /about, /status, /action.
• Режимы работы устройства:
  • setup — устройство ожидает настройки (доступны /setup, /about, /set_token без авторизации).
  • normal — устройство работает в штатном режиме (требуется токен).
  • error, updating — для расширения.
• Безопасность: Все запросы (кроме /about, /setup в режиме setup, /set_token в режиме setup) требуют передачи токена авторизации.

Авторизация

• Для всех эндпоинтов, кроме GET /about, GET/POST /setup (в режиме setup) и POST /set_token (в режиме setup), в запросах должен присутствовать заголовок:

  Authorization: Bearer <token>

• Без валидного токена устройство должно возвращать ошибку 401 Unauthorized.

Пример ответа при отсутствии или неверном токене

{
  "status": "error",
  "error": "Unauthorized",
  "message": "Missing or invalid token"
}

Эндпоинты

1. GET /about

Отдаёт базовую информацию об устройстве.

• Доступно всегда. Токен не требуется.

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

{
  "device_name": "Relay 1",
  "device_type": "relay",
  "firmware_version": "1.0.3",
  "device_id": "ecf0a1b5c9d74f9a8e294c1f67b0a8b9",
  "server": "http://192.168.1.10",
  "status": "normal",              // normal | setup | error | updating
  "ip_address": "192.168.1.42",
  "mac_address": "A4:CF:12:9B:3F:D2",
  "uptime": 123456                 // в секундах
}

2. GET /status

Отдаёт текущее состояние устройства.
В режиме normal требует заголовок Authorization с валидным токеном!
В режиме setup может быть недоступен или возвращать ограниченную информацию.

Пример для реле

{
  "state": "on"
}

Пример для температурного датчика

{
  "temperature_c": 21.8,
  "humidity_percent": 45.3,
  "battery_level": 93
}

3. POST /action

Позволяет управлять устройством.
В режиме normal требует заголовок Authorization с валидным токеном!
В режиме setup эндпоинт недоступен.

Пример запроса для реле

{
  "action": "set_state",
  "params": {
    "state": "off"
  }
}

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

{
  "status": "ok",
  "message": "State changed"
}

4. POST /set_token

Используется для первичной инициализации устройства (в режиме setup) и для смены токена по инициативе сервера (в режиме normal).

• В режиме setup: доступен без токена — сервер устанавливает токен впервые, переводит устройство в режим normal.
• В режиме normal: требует заголовок Authorization с валидным токеном! — смена токена доступна только авторизованному серверу.

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

{
  "token": "QmFzZVRva2VuU2FtcGxlMTIz"
}

Пример ответа (при успешной установке токена)

{
  "status": "ok",
  "message": "Token set. Device mode: normal"
}

Пример ошибки, если устройство уже в normal-режиме и попытка установки без токена

{
  "status": "error",
  "error": "Unauthorized",
  "message": "Missing or invalid token"
}

Пример ошибки, если устройство уже provisioned (уже переведено в normal и повторно в setup режим попасть нельзя)

{
  "status": "error",
  "error": "AlreadyProvisioned",
  "message": "Device already provisioned"
}

5. GET /setup и POST /setup

Доступно только в режиме setup.
Позволяет настроить подключение к Wi-Fi через веб-интерфейс.

Описание:

• Эндпоинт /setup доступен только, пока устройство находится в статусе setup (до получения токена).
• При обращении через браузер на /setup открывается веб-панель для ввода параметров Wi-Fi (SSID, пароль) и, при необходимости, адреса сервера.
• После успешной настройки и подключения к сети устройство переходит к процедуре ожидания установки токена (/set_token).
• После перехода в статус normal эндпоинт /setup становится недоступен (возвращает ошибку или заглушку).

Пример запроса (POST /setup):

{
  "ssid": "Home_WiFi",
  "password": "MySecretPass",
  "server": "http://192.168.1.10"
}

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

{
  "status": "ok",
  "message": "Wi-Fi configured. Connecting..."
}

Пример ошибки при попытке доступа к /setup вне режима setup:

{
  "status": "error",
  "error": "NotAvailable",
  "message": "Setup mode is not active"
}

6. POST /reboot

Физическая перезагрузка устройства.
Доступно только в режиме normal. Требует заголовок Authorization с валидным токеном!

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

{}

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

{
  "status": "ok",
  "message": "Device will reboot now"
}

7. POST /reset

Сброс всех настроек к заводским, переход в режим setup.
Доступно только в режиме normal. Требует заголовок Authorization с валидным токеном!

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

{}

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

{
  "status": "ok",
  "message": "Device reset to factory settings. Entering setup mode."
}

Рекомендации

• Все устройства реализуют эндпоинты /about, /status, /action.
• Для специфических функций устройства могут реализовать дополнительные эндпоинты по своему усмотрению.
• Поле device_type помогает серверу различать логику работы с устройством.
• Для расширения можно ввести версионирование схемы ответа (например, status_schema_version).

На будущее

• Добавить процедуру получения токена на сервере (админка).