REST API oder WebSocket

WLTE bietet sowohl REST API als auch WebSocket. Sie ersetzen sich nicht gegenseitig: Es sind zwei Kanäle, die für unterschiedliche Integrationsanforderungen konzipiert sind.

Grundmodell

REST API verwendet das standardmäßige Anfrage-Antwort-Modell. Ihr Server sendet eine HTTPS-Anfrage, und WLTE gibt eine explizite Antwort zurück. Geeignet zum Auflisten von Ressourcen, Abfragen von Ressourcen, Senden von Vorgängen und Lesen von Ergebnissen.

WebSocket verwendet ein Modell mit dauerhafter Verbindung. Ihr Server erstellt zunächst über REST ein einmaliges wsTicket und baut dann eine wss-Verbindung auf. Nach dem Verbindungsaufbau kann dieselbe Verbindung zum Senden von Anfragen und Empfangen von Geräteereignissen verwendet werden.

Wichtige Unterschiede

Dimension	REST API	WebSocket
Verbindung	Unabhängige HTTP-Anfrage pro Aufruf	Dauerhafte Verbindung, wiederholt genutzt
Interaktion	Eine Anfrage, eine Antwort	Anfragen senden, Antworten empfangen und Ereignisse empfangen
Am besten geeignet für	Listen, Paginierung, Konfiguration, Befehlsversand, Ergebnisabfrage	Echtzeit-Statusabfragen, latenzarme Interaktion, Ereigniszustellung
Zuverlässigkeitsmodell	Jede Anfrage hat ein explizites Ergebnis und kann HTTP-Wiederholungsregeln folgen	Verbindung kann abbrechen; Wiederholung von Ereignissen während des Abbruchs nicht garantiert
Autorisierung	Jeder geschützte Endpunkt prüft aktuelle Berechtigungen	Verbindung erfordert ein Ticket; aktive Anfragen prüfen weiterhin Vorgangsberechtigungen
Anfrageschutz	Abfragen und Gerätevorgänge sind ratenbegrenzt	Verbindungen, Nachrichten und Gerätevorgänge sind ratenbegrenzt
Integrationsaufwand	Einfacher, geeignet für die meisten Server-Integrationen	Komplexer: erfordert Heartbeat, Wiederverbindung und idempotente Ereignisverarbeitung

Wann REST API verwenden

Bevorzugen Sie REST API, wenn Sie Folgendes benötigen:

• Geräte eines Kontos anzeigen
• Geräte mit Paginierung laden
• Gerätetypdefinitionen lesen
• Relais-, RS485- oder Konfigurationsvorgänge erstellen
• Befehlsergebnis abfragen
• Serverseitige geplante Synchronisierung ausführen
• Mit klaren HTTP-Statuscodes und Geschäftsfehlercodes arbeiten

Typischer Ablauf:

Access Token erhalten
-> GET /wlte/v1/devices
-> GET /wlte/v1/devices/{deviceId}
-> POST /wlte/v1/devices/{deviceId}/relays/commands
-> GET /wlte/v1/commands/{commandId}

Wann WebSocket verwenden

Ziehen Sie WebSocket in Betracht, wenn Ihr Server Folgendes benötigt:

• Verbunden bleiben und Geräteereignisse empfangen
• Echtzeitstatus eines einzelnen Geräts mit geringer Latenz abfragen
• Gerätezustand innerhalb eines Serviceprozesses aktuell halten
• Latenz durch wiederholten HTTP-Verbindungsaufbau reduzieren

Typischer Ablauf:

Access Token erhalten
-> POST /wlte/v1/ws/ticket
-> Verbindung zu wss://.../wlte/v1/ws?ticket=... herstellen
-> session.ping als Anwendungs-Heartbeat senden
-> device.state.get für den Echtzeitstatus eines Geräts senden
-> device.operation.execute für Gerätevorgänge senden
-> Geräteereignisse empfangen

Empfohlene Kombination

Die meisten Produktionsintegrationen sollten beide verwenden:

1. Verwenden Sie REST API für Initialisierung und Backup-Synchronisierung.
2. Verwenden Sie WebSocket für Echtzeitänderungen und Echtzeitstatusabfragen eines einzelnen Geräts.
3. Verwenden Sie nach einer WebSocket-Trennung oder einem Dienstneustart REST API, um den Basiszustand wiederherzustellen.
4. Verlassen Sie sich nicht nur auf WebSocket-Ereignisse für kritischen Geschäftszustand: Behalten Sie immer die Möglichkeit, ihn über REST API zu bestätigen.

Häufige Fehler

Aktualisierung aller Kontogeräte über WebSocket

Nicht empfohlen. device.state.get ist für den Echtzeitstatus eines einzelnen Geräts gedacht und kann eine tatsächliche Aktualisierung sowie geräteseitige Ratenbegrenzungen auslösen. Verwenden Sie für Kontogerätelisten Geräte auflisten (auf Englisch).

Annahme, dass WebSocket nie die Verbindung trennt

Gehen Sie nicht davon aus. Netzwerkänderungen, Deployments, Proxys, Dienstneustarts und Client-Prozessneustarts können die Verbindung schließen. Der Client muss Wiederverbindung, Heartbeat und idempotente Ereignisverarbeitung implementieren.

Ersetzen aller Statusabfragen durch WebSocket-Ereignisse

Nicht empfohlen. WebSocket dient der Echtzeitbenachrichtigung, sollte aber nicht die einzige dauerhafte Zustandsquelle sein. Bestätigen Sie nach einer Zustandslücke, einem Seiten-Reload oder einem Dienstneustart den Zustand erneut über REST API oder device.state.get.

Schnelle Entscheidungstabelle

Bedarf	Empfehlung
Erste Integration oder API-Validierung	REST API
Geräteliste anzeigen	REST API
Benutzer öffnet Gerätedetails und aktualisiert sie	REST API GET /devices/{deviceId} oder WS device.state.get
Server benötigt kontinuierliche Änderungsereignisse	WebSocket
Gerätesteuerung ausführen	REST API oder device.operation.execute über eine bereits geöffnete WebSocket-Verbindung
Endergebnis eines Befehls abfragen	REST API
Zustand nach WebSocket-Trennung wiederherstellen	Über REST API resynchronisieren, dann mit WebSocket fortfahren