REST API ou WebSocket

O WLTE oferece REST API e WebSocket. Eles não se substituem: são dois canais projetados para necessidades de integração diferentes.

Modelo básico

A REST API usa o modelo padrão de requisição e resposta. Seu servidor envia uma requisição HTTPS e o WLTE retorna uma resposta explícita. É adequada para listar recursos, consultar recursos, enviar operações e ler seus resultados.

O WebSocket usa um modelo de conexão persistente. Seu servidor primeiro cria um wsTicket de uso único via REST, depois estabelece uma conexão wss. Depois de estabelecida, a mesma conexão pode ser usada para enviar requisições e receber eventos de dispositivo.

Principais diferenças

Dimensão	REST API	WebSocket
Conexão	Uma requisição HTTP independente por chamada	Conexão persistente reutilizada ao longo do tempo
Interação	Uma requisição, uma resposta	Envia requisições, recebe respostas e recebe eventos
Ideal para	Listas, paginação, configuração, envio de comandos, consulta de resultados	Consultas de estado em tempo real, interação de baixa latência, entrega de eventos
Modelo de confiabilidade	Cada requisição tem um resultado explícito e segue as regras de retry HTTP	A conexão pode cair; não há garantia de reprodução dos eventos ocorridos durante a queda
Autorização	Cada endpoint protegido valida as permissões atuais	A conexão exige um ticket; requisições ativas ainda validam as permissões da operação
Proteção de requisições	Consultas e operações em dispositivos têm limite de taxa	Conexões, mensagens e operações em dispositivos têm limite de taxa
Custo de integração	Mais simples, adequado para a maioria das integrações de servidor	Mais complexo: exige heartbeat, reconexão e tratamento idempotente de eventos

Quando usar REST API

Prefira REST API quando precisar:

• Exibir os dispositivos de uma conta
• Carregar dispositivos com paginação
• Consultar as definições de tipo de dispositivo
• Criar operações de relé, RS485 ou configuração
• Consultar o resultado de um comando
• Executar sincronizações programadas no servidor
• Trabalhar com códigos de status HTTP e códigos de erro de negócio claros

Fluxo típico:

Obter access token
-> GET /wlte/v1/devices
-> GET /wlte/v1/devices/{deviceId}
-> POST /wlte/v1/devices/{deviceId}/relays/commands
-> GET /wlte/v1/commands/{commandId}

Quando usar WebSocket

Considere WebSocket quando seu servidor precisar:

• Permanecer conectado e receber eventos de dispositivo
• Consultar o estado em tempo real de um dispositivo com baixa latência
• Manter o estado dos dispositivos vivo dentro de um processo de serviço
• Reduzir a latência de abrir conexões HTTP repetidamente

Fluxo típico:

Obter access token
-> POST /wlte/v1/ws/ticket
-> Conectar a wss://.../wlte/v1/ws?ticket=...
-> Enviar session.ping como heartbeat da aplicação
-> Enviar device.state.get para o estado em tempo real de um dispositivo
-> Enviar device.operation.execute para operar o dispositivo
-> Receber eventos de dispositivo

Combinação recomendada

A maioria das integrações em produção deve usar ambos:

1. Use REST API para inicialização e sincronização de reserva.
2. Use WebSocket para mudanças em tempo real e consultas de estado de um dispositivo.
3. Após uma desconexão do WebSocket ou reinício do serviço, use REST API para reconstruir a base de estado.
4. Não dependa apenas dos eventos WebSocket para o estado crítico do seu negócio: tenha sempre como confirmá-lo via REST API.

Erros comuns

Atualizar todos os dispositivos da conta via WebSocket

Não é recomendado. device.state.get é para o estado em tempo real de um único dispositivo e pode disparar uma atualização real e os limites de taxa por dispositivo. Para listar os dispositivos de uma conta, use Listar dispositivos (em inglês).

Assumir que o WebSocket nunca desconecta

Não assuma isso. Mudanças de rede, deploys, proxies, reinícios de serviço e reinícios do processo cliente podem fechar a conexão. O cliente deve implementar reconexão, heartbeat e tratamento idempotente de eventos.

Substituir todas as consultas de estado por eventos WebSocket

Não é recomendado. O WebSocket serve para notificar em tempo real, mas não deve ser a única fonte permanente de estado. Após uma lacuna de estado, um recarregamento de página ou um reinício do serviço, confirme o estado novamente via REST API ou com device.state.get.

Tabela de decisão rápida

Necessidade	Recomendação
Primeira integração ou validação da API	REST API
Exibir uma lista de dispositivos	REST API
O usuário abre o detalhe de um dispositivo e atualiza	REST API GET /devices/{deviceId} ou WS device.state.get
O servidor precisa de eventos contínuos de mudança	WebSocket
Executar controle de dispositivo	REST API, ou device.operation.execute em uma conexão WebSocket já aberta
Consultar o resultado final de um comando	REST API
Recuperar o estado após uma desconexão do WebSocket	Resincronize com REST API e continue com WebSocket