REST API или WebSocket

WLTE предоставляет и REST API, и WebSocket. Они не заменяют друг друга: это два канала, разработанные для разных задач интеграции.

Базовая модель

REST API использует стандартную модель запрос-ответ. Ваш сервер отправляет один HTTPS-запрос, а WLTE возвращает один явный ответ. Подходит для получения списков ресурсов, их запроса, отправки операций и чтения результатов.

WebSocket использует модель постоянного соединения. Ваш сервер сначала создаёт одноразовый wsTicket через REST, затем устанавливает соединение wss. После установления соединения его можно использовать для отправки запросов и получения событий устройств.

Ключевые различия

Параметр	REST API	WebSocket
Соединение	Независимый HTTP-запрос на каждый вызов	Постоянное соединение, используемое многократно
Взаимодействие	Один запрос, один ответ	Отправка запросов, получение ответов и получение событий
Лучше всего подходит для	Списков, пагинации, конфигурации, отправки команд, получения результатов	Запросов состояния в реальном времени, взаимодействия с низкой задержкой, доставки событий
Модель надёжности	Каждый запрос имеет явный результат и может следовать правилам повторных попыток HTTP	Соединение может разорваться; повторная передача событий, произошедших во время разрыва, не гарантируется
Авторизация	Каждая защищённая конечная точка проверяет текущие права доступа	Соединение требует тикет; активные запросы по-прежнему проверяют права на операцию
Защита запросов	Запросы и операции с устройствами ограничены по частоте	Соединения, сообщения и операции с устройствами ограничены по частоте
Стоимость интеграции	Проще, подходит для большинства серверных интеграций	Сложнее: требует heartbeat, переподключения и идемпотентной обработки событий

Когда использовать REST API

Предпочитайте REST API, когда вам нужно:

• Отобразить устройства учётной записи
• Загрузить устройства с постраничной разбивкой
• Прочитать определения типов устройств
• Создать операции реле, RS485 или конфигурации
• Запросить результат команды
• Выполнить плановую синхронизацию на стороне сервера
• Работать с понятными кодами состояния HTTP и бизнес-кодами ошибок

Типичный поток:

Получить access token
-> GET /wlte/v1/devices
-> GET /wlte/v1/devices/{deviceId}
-> POST /wlte/v1/devices/{deviceId}/relays/commands
-> GET /wlte/v1/commands/{commandId}

Когда использовать WebSocket

Рассмотрите WebSocket, если вашему серверу нужно:

• Оставаться на связи и получать события устройств
• Запрашивать состояние одного устройства в реальном времени с низкой задержкой
• Поддерживать актуальное состояние устройств внутри процесса-сервиса
• Снизить задержку от повторного установления HTTP-соединений

Типичный поток:

Получить access token
-> POST /wlte/v1/ws/ticket
-> Подключиться к wss://.../wlte/v1/ws?ticket=...
-> Отправлять session.ping как heartbeat приложения
-> Отправить device.state.get для состояния одного устройства в реальном времени
-> Отправить device.operation.execute для операций с устройством
-> Получать события устройств

Рекомендуемая комбинация

Большинству продакшн-интеграций стоит использовать оба варианта:

1. Используйте REST API для инициализации и резервной синхронизации.
2. Используйте WebSocket для изменений в реальном времени и запросов состояния одного устройства.
3. После разрыва WebSocket или перезапуска сервиса используйте REST API для восстановления базового состояния.
4. Не полагайтесь только на события WebSocket для критичного бизнес-состояния: всегда сохраняйте возможность подтвердить его через REST API.

Типичные ошибки

Обновление всех устройств учётной записи через WebSocket

Не рекомендуется. device.state.get предназначен для состояния одного устройства в реальном времени и может вызвать реальное обновление и лимиты по частоте на уровне устройства. Для списков устройств учётной записи используйте Получение списка устройств (на английском).

Предположение, что WebSocket никогда не разрывается

Не стоит так считать. Изменения сети, развёртывания, прокси, перезапуски сервиса и перезапуски клиентского процесса могут закрыть соединение. Клиент должен реализовать переподключение, heartbeat и идемпотентную обработку событий.

Замена всех запросов состояния событиями WebSocket

Не рекомендуется. WebSocket предназначен для уведомлений в реальном времени, но не должен быть единственным постоянным источником состояния. После пробела в состоянии, перезагрузки страницы или перезапуска сервиса подтвердите состояние повторно через REST API или device.state.get.

Таблица быстрых решений

Потребность	Рекомендация
Первая интеграция или проверка API	REST API
Отображение списка устройств	REST API
Пользователь открывает детали устройства и обновляет их	REST API GET /devices/{deviceId} или WS device.state.get
Серверу нужны непрерывные события изменений	WebSocket
Выполнение управления устройством	REST API или device.operation.execute через уже открытое соединение WebSocket
Запрос финального результата команды	REST API
Восстановление состояния после разрыва WebSocket	Синхронизация через REST API, затем продолжение работы с WebSocket