コンテンツにスキップ

[章番号]: WebSocket API仕様書

このテンプレートの使い方

このファイルは、WebSocketによるリアルタイム双方向通信APIの仕様を定義するためのテンプレートです。 接続のライフサイクルと、サーバー・クライアント間で送受信される「メッセージ（イベント）」の仕様を定義することに重点を置きます。 詳しい使い方は「設計仕様の書き方ガイド」を参照してください。

1. はじめに

1.1. 目的

1.2. 対象読者

2. 基本情報

項目 内容
接続エンドポイントURL wss://api.example.com/v1/socket
データ形式 JSON (UTF-8)
認証方式 [例: 接続URLのクエリパラメータにアクセストークンを含める] (詳細はAPI設計共通ガイドラインを参照)
再接続ポリシー [例: 指数バックオフ戦略を推奨]

3. 接続ライフサイクル

  • 接続確立:
    • クライアントは指定のエンドポイントURLにWebSocket接続を試みます。
    • 認証が成功すると、サーバーは接続を確立し、connection_ack メッセージを送信します。
  • 接続維持 (ハートビート):
    • [例: サーバーは30秒ごとに ping メッセージを送信し、クライアントは pong メッセージで応答する必要があります。]
  • 接続切断:
    • サーバーまたはクライアントのいずれかが接続を閉じることができます。
    • サーバーは、異常な切断（例: 認証トークンの失効）の場合、特定のクローズコードと共に接続を閉じることがあります。

4. メッセージ形式

全てのメッセージは、以下のJSON形式に従います。

{
    "event": "イベント名",
    "payload": {
        // イベント固有のデータ
    },
    "sequence": 12345 // (任意) メッセージのシーケンス番号
}
フィールド名 型 説明
event string メッセージの種類を識別するイベント名。
payload object イベントに関連するデータを含むオブジェクト。
sequence integer (任意) メッセージの順序を保証するためのシーケンス番号。

5. サーバーからクライアントへのメッセージ

5.1. connection_ack

  • 概要: WebSocket接続が正常に確立されたことを通知する。
  • ペイロード:
{
    "sessionId": "session-abcdef123"
}

5.2. new_message

  • 概要: 新しいチャットメッセージが投稿されたことを通知する。
  • ペイロード:
{
    "channelId": "channel-001",
    "message": {
        "id": "msg-xyz789",
        "text": "こんにちは！",
        "author": {
            "id": "user-001",
            "name": "Taro Yamada"
        },
        "timestamp": "2025-07-28T12:00:00Z"
    }
}

6. クライアントからサーバーへのメッセージ

6.1. join_channel

  • 概要: 特定のチャンネルのメッセージ購読を開始する。
  • ペイロード:
{
    "channelId": "channel-001"
}

6.2. send_message

  • 概要: チャンネルに新しいメッセージを投稿する。
  • ペイロード:
{
    "channelId": "channel-001",
    "text": "API仕様書を書いています。"
}

7. エラーハンドリング

7.1. error

  • 概要: 操作が失敗した、または不正なメッセージを受信した際にエラーを通知する。
  • ペイロード:
{
    "code": "PERMISSION_DENIED",
    "message": "You do not have permission to join this channel.",
    "originalEvent": "join_channel" // (任意) エラーの原因となったイベント
}