REST APIかWebSocketか

WLTEはREST APIとWebSocketの両方を提供しています。両者は互いの代替ではなく、異なる統合ニーズのために設計された2つのチャネルです。

基本モデル

REST APIは標準的なリクエスト・レスポンスモデルを使用します。サーバーが1つのHTTPSリクエストを送信すると、WLTEは1つの明示的なレスポンスを返します。リソースの一覧取得、照会、操作の送信、操作結果の読み取りに適しています。

WebSocketは永続的な接続モデルを使用します。サーバーはまずRESTで一度限りの wsTicket を作成し、次に wss 接続を確立します。接続が確立された後は、同じ接続でリクエストの送信とデバイスイベントの受信ができます。

主な違い

観点	REST API	WebSocket
接続	呼び出しごとに独立したHTTPリクエスト	時間をまたいで再利用される永続的な接続
やり取り	1リクエスト、1レスポンス	リクエスト送信、応答受信、イベント受信
適している用途	一覧、ページング、設定、コマンド送信、結果照会	リアルタイム状態照会、低遅延なやり取り、イベント配信
信頼性モデル	各リクエストは明示的な結果を持ち、HTTPのリトライルールに従える	接続が切れることがあり、切断中のイベントは再送されるとは限らない
認可	保護されたエンドポイントはすべて現在の権限を検証する	接続にはチケットが必要で、実行中のリクエストも操作権限を検証する
リクエスト保護	照会とデバイス操作にレート制限がある	接続・メッセージ・デバイス操作にレート制限がある
統合コスト	よりシンプルで、多くのサーバー統合に適している	より複雑。ハートビート、再接続、冪等なイベント処理が必要

REST APIを使うべき場面

次のような場合はREST APIを優先してください。

• アカウント配下のデバイスを表示する
• デバイスをページングで読み込む
• デバイスタイプ定義を読み取る
• リレー、RS485、設定操作を作成する
• コマンド結果を照会する
• サーバー側の定期同期を実行する
• 明確なHTTPステータスコードとビジネスエラーコードを使う

典型的なフロー:

アクセストークンを取得
-> GET /wlte/v1/devices
-> GET /wlte/v1/devices/{deviceId}
-> POST /wlte/v1/devices/{deviceId}/relays/commands
-> GET /wlte/v1/commands/{commandId}

WebSocketを使うべき場面

サーバーに次のニーズがある場合はWebSocketを検討してください。

• 常時接続を維持し、デバイスイベントを受信する
• 単一デバイスのリアルタイム状態を低遅延で照会する
• サービスプロセス内でデバイスの最新状態を保持する
• HTTP接続の確立を繰り返すことによる遅延を減らす

典型的なフロー:

アクセストークンを取得
-> POST /wlte/v1/ws/ticket
-> wss://.../wlte/v1/ws?ticket=... に接続
-> アプリケーションのハートビートとして session.ping を送信
-> 単一デバイスのリアルタイム状態のために device.state.get を送信
-> デバイス操作のために device.operation.execute を送信
-> デバイスイベントを受信

推奨される組み合わせ

多くの本番統合では、両方を使うべきです。

1. 初期化とフォールバック同期にはREST APIを使う。
2. リアルタイムな変化と単一デバイスのリアルタイム状態照会にはWebSocketを使う。
3. WebSocketが切断された後、またはサービス再起動後は、REST APIで状態のベースラインを再構築する。
4. 重要なビジネス状態をWebSocketイベントだけに依存しない。REST APIで改めて状態を確認できるようにしておく。

よくある誤り

WebSocket経由でアカウント全体のデバイスを更新する

推奨されません。device.state.get は1台のデバイスのリアルタイム状態向けであり、リアルタイム更新やデバイス単位のレート制限を引き起こす可能性があります。アカウントのデバイス一覧にはデバイス一覧の取得（英語）を使ってください。

WebSocketは切断されないと想定する

そう想定してはいけません。ネットワークの変化、デプロイ、プロキシ、サービス再起動、クライアントプロセスの再起動はいずれも接続を閉じる可能性があります。クライアントは再接続、ハートビート、冪等なイベント処理を実装する必要があります。

すべての状態照会をWebSocketイベントで置き換える

推奨されません。WebSocketはリアルタイム通知のためのものであり、唯一の永続的な状態のソースにしてはいけません。状態のギャップ、ページの再読み込み、サービス再起動の後は、REST APIまたは device.state.get で改めて状態を確認してください。

クイック判断表

必要なこと	推奨
初回統合またはAPI検証	REST API
デバイス一覧の表示	REST API
ユーザーが1台のデバイス詳細ページを開いて更新する	REST APIの GET /devices/{deviceId} またはWSの device.state.get
サーバーが継続的なデバイス変化イベントを必要とする	WebSocket
デバイス制御の実行	REST API、または既存のWebSocket接続上の device.operation.execute
最終的なコマンド結果の照会	REST API
WebSocket切断後の状態復旧	REST APIで再同期してからWebSocketを継続