REST API vs WebSocket

WLTE provides both REST API and WebSocket. They are not replacements for each other. They are two channels designed for different integration needs.

Basic Model

REST API uses a standard request-response model. Your server sends one HTTPS request, and WLTE returns one explicit response. It is suitable for listing resources, querying resources, submitting operations, and reading operation results.

WebSocket uses a persistent connection model. Your server first creates a one-time wsTicket through REST, then establishes a wss connection. After the connection is established, the same connection can be used to send requests and receive device events.

Key Differences

Dimension	REST API	WebSocket
Connection	Independent HTTP request per call	Persistent connection reused over time
Interaction	One request, one response	Send request, receive reply, and receive events
Best for	Lists, pagination, configuration, command submission, result lookup	Real-time state queries, low-latency interaction, event delivery
Reliability model	Each request has an explicit result and can follow HTTP retry rules	Connections may disconnect; events during disconnection are not guaranteed to be replayed
Authorization	Every protected endpoint validates current permissions	Connection requires a ticket; active requests still validate operation permissions
Request protection	Queries and device operations are rate limited	Connections, messages, and device operations are rate limited
Integration cost	Simpler and suitable for most server integrations	More complex; requires heartbeat, reconnect, and idempotent event handling

When To Use REST API

Prefer REST API when you need to:

• Display the devices under an account
• Load devices with pagination
• Read device type definitions
• Create relay, RS485, or configuration operations
• Query command results
• Run server-side scheduled synchronization
• Use clear HTTP status codes and business error codes

Typical flow:

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

When To Use WebSocket

Consider WebSocket when your server needs to:

• Stay online and receive device events
• Query the real-time state of a single device with low latency
• Maintain live device state in a service process
• Reduce latency from repeated HTTP connection setup

Typical flow:

Get access token
-> POST /wlte/v1/ws/ticket
-> Connect to wss://.../wlte/v1/ws?ticket=...
-> Send session.ping as an application heartbeat
-> Send device.state.get for a single device's real-time state
-> Send device.operation.execute for device operations
-> Receive device events

Recommended Combination

Most production integrations should use both:

1. Use REST API for initialization and fallback synchronization.
2. Use WebSocket for real-time changes and single-device real-time state queries.
3. After a WebSocket disconnect or service restart, use REST API to rebuild the state baseline.
4. Do not rely only on WebSocket events for critical business state. Be able to confirm state again through REST API.

Common Mistakes

Refreshing all account devices through WebSocket

Not recommended. device.state.get is for one device's real-time state and may trigger real-time refresh and device-level rate limits. Use List Devices for account device lists.

Assuming WebSocket never disconnects

Do not assume that. Network changes, deployments, proxies, service restarts, and client process restarts can all close the connection. Clients must implement reconnect, heartbeat, and idempotent event handling.

Replacing all state queries with WebSocket events

Not recommended. WebSocket is for real-time notifications, but it should not be the only permanent source of state. After a state gap, page reload, or service restart, use REST API or device.state.get to confirm state again.

Quick Decision Table

Need	Recommended
First integration or API validation	REST API
Display a device list	REST API
User opens one device detail page and refreshes	REST API GET /devices/{deviceId} or WS device.state.get
Server needs continuous device change events	WebSocket
Execute device control	REST API, or device.operation.execute on an existing WebSocket connection
Query the final command result	REST API
Recover state after WebSocket disconnect	Resync with REST API, then continue WebSocket