Rocket Home API

OAuth2 авторизация

Клиент-нейтральный REST API в стиле Kubernetes group/version: /api/{group}/{version}/{resource} (локация — namespace). Для доступа используйте обычный OAuth2 Authorization Code flow (PKCE рекомендуется); bearer token передаётся в Authorization: Bearer <access_token>.

1. Обнаружьте поверхность: GET /api (группы) и GET /api/{group} (версии/ресурсы); метаданные OAuth — /.well-known/oauth-authorization-server (RFC 8414).
2. Перенаправьте пользователя на /oauth/authorize?client_id=...&redirect_uri=...&response_type=code&scope=....
3. После подтверждения доступа обменяйте полученный code на токены через POST /oauth/token.
4. Используйте access_token как bearer для вызовов API.
5. Когда access_token истечёт, обновите его через POST /oauth/token с grant_type=refresh_token.
6. Для отзыва текущего набора токенов вызовите POST /oauth/revoke с текущим bearer token.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://example.com/callback
&code=AUTHORIZATION_CODE

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Scopes — матрица rh.<resource>:<action>: rh.profile:read, rh.structure:read, rh.devices:read, rh.devices:control, rh.automations:read, rh.automations:write, rh.mqtt:connect. К любому scope можно добавить qualifier-сужение @location:{uuid} или @room:{uuid}; несколько ограничений = несколько scope-строк (эффект — объединение).

В ответах группы devices (GET /api/devices/v1/locations/{loc}/devices) у каждого устройства есть блок mqtt и список exposes. Используйте mqtt.status_topic для чтения состояния, mqtt.command_topic для publish-команд и exposes для понимания допустимых действий, MQTT payload keys, единиц измерения и диапазонов значений. Поле topic сохранено как совместимый alias для mqtt.status_topic.

Каждый expose может содержать блоки transport и normalized. Блок transport описывает реальные raw-значения MQTT payload (например, brightness 0..254), а normalized — человеко-понятные значения для UI (например, brightness 0..100%). Если driver-specific override отсутствует, transport будет null, а normalized заполнен из общих metadata.

Поля устройства в ответе API

Ниже — как использовать поля объекта устройства при интеграции (MQTT-агент, автоматизации, дашборды).

• id, room_id — идентификаторы для ссылок в API и привязки к комнате/локации.
• type, title, description — тип шаблона устройства и отображаемое имя.
• custom_data — служебные данные интеграции: как минимум driver (zigbee2mqtt, amethyst, и т.д.) и идентификаторы для топика (friendly_name, при необходимости tag). От них зависят mqtt.* и наличие exposes.
• capabilities — что на устройстве настроено как «управляемое» (яркость, вкл/выкл и т.д.). Поле capability_function_name совпадает с exposes[].name для записей с kind: capability.
• properties — только чтение (датчики, статусы). property_function_name совпадает с exposes[].name при kind: property.
• topic — то же, что mqtt.status_topic (алиас для старых клиентов).
• mqtt.driver — какой бэкенд формирует топики и семантику payload.
• mqtt.status_topic — подписка на JSON-состояние устройства.
• mqtt.command_topic — публикация команд; обычно это status_topic + /set. Тело — JSON, ключи из capability-exposes (mqtt_keys).
• exposes — сводная «контрактная» карта: для каждой функции указаны MQTT-ключи, типы, при необходимости transport (как в брокере) и normalized (удобно для UI). Корневые value_range / enum_values — совместимый слой; при ненулевом transport для команд ориентируйтесь на transport.min/max/value_type.
• privileged, is_hidden — флаги доступа и видимости в интерфейсах.

Поток для агента: получить MQTT-JWT через GET /api/mqtt/v1/token (scope rh.mqtt:connect) → подключиться к MQTT → подписаться на status_topic → по exposes сопоставить ключи JSON с именами свойств → для управления публиковать в command_topic объект с ключами из mqtt_keys и значениями в шкале transport (если задана), иначе по value_range/enum.