SkyWay Room API

SkyWay Room API は、SkyWay の Room に対する操作を実行するサーバーサイド向け API です。 API は JSON-RPC 2.0 に準拠しています。

API エンドポイント

https://room.skyway.ntt.com/v1/json-rpc

HTTP POST メソッドでリクエストを行なってください。

認証

リクエストの Authorization ヘッダーに SkyWay Admin Auth Token を入れる必要があります。 YOUR_SKYWAY_ADMIN_AUTH_TOKEN は生成した SkyWay Admin Auth Token で置き換えてください。

Authorization: Bearer YOUR_SKYWAY_ADMIN_AUTH_TOKEN

SkyWay Admin Auth Token の詳細については SkyWay Admin Auth Token のドキュメントを参照してください。

エラーレスポンスについて

エラーレスポンスのレスポンスボディに含まれる error.code は JSON-RPC 2.0 の Error object で定義されているエラーコードのほか、SkyWay Room API として以下のコードを定義しています。

code	説明
401	SkyWay Admin Auth Token が不正な場合
404	リソースが見つからなかった場合
409	すでにリソースが存在する場合
429	Free プランをご利用のプロジェクトで月次の接続回数制限を超過している場合
429	リクエストのレートリミットを超過した場合

以下のエラーレスポンスは、実行する Room API のメソッドに関わらず共通して発生し得る異常ケースです。

SkyWay Admin Auth Token が不正な場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": 401,
    "message": "Verify admin token failed"
  }
}

Free プランをご利用のプロジェクトで月次の接続回数制限※を超過している場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": 429,
    "message": "Project usage limit has been exceeded"
  }
}

※接続回数の上限は「プランの詳細」ページの「接続料」をご確認ください。

リクエストのレートリミット※を超過した場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": 429,
    "message": "exceeded rate limit",
  }
}

※リクエストレートの制限に関する詳細は「割り当てと制限」ページの「リクエストレートの制限」セクションをご確認ください。

リクエストボディの id プロパティが文字列もしくは整数以外の場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "Request 'id' must be a string or integer",
  }
}

findRoom

id または name から Room を取得します。 id と name の両方が指定された場合は id に基づいて Room を取得します。

リクエストボディ

プロパティ	形式	必須	説明
jsonrpc	string	️✔	`2.0` を指定する
id	string \| integer	✔	任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る
method	string	✔	`findRoom` を指定する
params	object	✔	Room の id または name を指定する（id あるいは name のいずれかは必須）

params プロパティの構造

プロパティ	形式	必須	説明
id	string (UUID v4)		Room の id を指定する
name	string		Room の name を指定する

例 1. id 6abbecae-dd86-4e8b-ab9f-8da2c7740ddc の Room を取得する場合のリクエストボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "findRoom",
  "params": {
    "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc"
  }
}

例 2. name sample-room の Room を取得する場合のリクエストボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "findRoom",
  "params": {
    "name": "sample-room"
  }
}

レスポンスボディ

正常系

レスポンスボディ

プロパティ	形式	必須	説明
jsonrpc	string	️✔	`2.0` が入る
id	string \| integer	✔	リクエストボディで指定した id の値が入る
result	object	✔
result.room	Room	✔	Room 情報を表すオブジェクト

Room オブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	️✔	Room を一意に特定する値
name	string		アプリケーション内で Room を一意に特定する値
expiresAt	string	✔	Room の失効時刻（ISO 8601 形式）
members	Member[]	✔	Member 情報を表すオブジェクトの配列
publications	Publication[]	✔	Publication 情報を表すオブジェクトの配列
subscriptions	Subscription[]	✔	Subscription 情報を表すオブジェクトの配列
metadata	string

Member オブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	️✔	Member を一意に特定する値
name	string		Room 内で Member を一意に特定する値
metadata	string

Publication オブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	️✔	Publication を一意に特定する値
publisher	Publisher	✔	Publish している Member の情報
contentType	string	✔	`AUDIO`、`VIDEO` または `DATA` が入る
isEnabled	boolean	✔	Publication が有効の場合 `true`、そうでなければ `false` が入る
type	string	✔	`P2P` または `SFU` が入る
metadata	string

Publisher オブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	️✔	Publisher の Member id
name	string		Publisher の Member name

Subscription オブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	️✔	Subscription を一意に特定する値
publicationId	string (UUID v4)	️✔	subscribe している Publication の id
subscriber	Subscriber	✔	subscribe している Member の情報

Subscriber オブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	️✔	Subscriber の Member id
name	string		Subscriber の Member name

例

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "room": {
      "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc",
      "name": "sample-room",
      "expiresAt": "2025-11-25T12:34:56Z",
      "members": [
        {
          "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3",
          "name": "user01",
          "metadata": "publisher"
        },
        {
          "id": "504ac623-7880-49b5-855f-aa73856ae5e7",
          "name": "user02",
          "metadata": "subscriber"
        }
      ],
      "publications": [
        {
          "id": "aa63b6d1-c1c5-447b-b7ea-faebe70a8b11",
          "contentType": "VIDEO",
          "isEnabled": true,
          "type": "SFU",
          "publisher": {
            "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3",
            "name": "user01"
          }
        },
        {
          "id": "7b213f12-42ba-40f2-9b36-9eb967d263d6",
          "contentType": "DATA",
          "isEnabled": true,
          "type": "P2P",
          "publisher": {
            "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3",
            "name": "user01"
          }
        }
      ],
      "subscriptions": [
        {
          "id": "be35b8dc-bcc3-4005-bf2a-b4d52d51f2db",
          "publicationId": "aa63b6d1-c1c5-447b-b7ea-faebe70a8b11",
          "subscriber": {
            "id": "504ac623-7880-49b5-855f-aa73856ae5e7",
            "name": "user02"
          }
        },
        {
          "id": "4fcef9c1-3f7a-4287-92de-332c2baf3ce6",
          "publicationId": "7b213f12-42ba-40f2-9b36-9eb967d263d6",
          "subscriber": {
            "id": "504ac623-7880-49b5-855f-aa73856ae5e7",
            "name": "user02"
          }
        }
      ]
    }
  }
}

異常系

例 1. 指定した id の Room が存在しなかった場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": 404,
    "message": "Room '6abbecae-dd86-4e8b-ab9f-8da2c7740ddc' not found"
  }
}

例 2. 指定した name の Room が存在しなかった場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": 404,
    "message": "Room with name 'sample-room' not found"
  }
}

例 3. Room の id および name がどちらも指定されていない場合

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": -32602,
    "message": "'id' or 'name' must be specified",
  },
}

createRoom

Room を新規作成します。作成時に name や metadata を指定することができます。

リクエストボディ

プロパティ	形式	必須	説明
jsonrpc	string	️✔	`2.0` を指定する
id	string \| integer	✔	任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る
method	string	✔	`createRoom` を指定する
params	object	✔	Room の name および metadata を指定できる

params プロパティの構造

プロパティ	形式	必須	説明
name	string		Room の name を指定する。アプリケーション内で一意である必要がある
metadata	string		Room の metadata を指定する

例 1. sample-room という name を指定して Room を作成する場合のリクエストボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "createRoom",
  "params": {
    "name": "sample-room"
  }
}

例 2. name を指定しないで Room を作成する場合のリクエストボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "createRoom",
  "params": {}
}

レスポンスボディ

正常系

レスポンスボディ

プロパティ	形式	必須	説明
jsonrpc	string	️✔	`2.0` が入る
id	string \| integer	✔	リクエストボディで指定した id の値が入る
result	object	✔
result.room	Room	✔	Room 情報を表すオブジェクト

Room オブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	️✔	Room を一意に特定する値
name	string		アプリケーション内で Room を一意に特定する値
metadata	string

例

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "room": {
      "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc",
      "name": "sample-room"
    }
  },
}

異常系

例 1. 指定した name の Room がすでに存在していた場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": 409,
    "message": "Room with name 'sample-room' already exists"
  }
}

findOrCreateRoom

指定された name の Room が存在すればその Room 情報を取得し、そうでなければ新規作成します。

リクエストボディ

プロパティ	形式	必須	説明
jsonrpc	string	️✔	`2.0` を指定する
id	string \| integer	✔	任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る
method	string	✔	`findOrCreateRoom` を指定する
params	object	✔	Room の name および metadata を指定する（name は必須）

params プロパティの構造

プロパティ	形式	必須	説明
name	string	✔	Room の name を指定する
metadata	string		Room の metadata を指定する

例

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "findOrCreateRoom",
  "params": {
    "name": "sample-room"
  }
}

レスポンスボディ

正常系

レスポンスボディ

プロパティ	形式	必須	説明
jsonrpc	string	️✔	`2.0` が入る
id	string \| integer	✔	リクエストボディで指定した id の値が入る
result	object	✔
result.room	Room	✔	Room 情報を表すオブジェクト

Room オブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	️✔	Room を一意に特定する値
name	string		アプリケーション内で Room を一意に特定する値
expiresAt	string	✔	Room の失効時刻（ISO 8601 形式）
members	Member[]	✔	Member 情報を表すオブジェクトの配列
publications	Publication[]	✔	Publication 情報を表すオブジェクトの配列
subscriptions	Subscription[]	✔	Subscription 情報を表すオブジェクトの配列
metadata	string

Member オブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	️✔	Member を一意に特定する値
name	string		Room 内で Member を一意に特定する値
metadata	string

Publication オブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	️✔	Publication を一意に特定する値
publisher	Publisher	✔	Publish している Member の情報
contentType	string	✔	`AUDIO`、`VIDEO` または `DATA` が入る
isEnabled	boolean	✔	Publication が有効の場合 `true`、そうでなければ `false` が入る
type	string	✔	`P2P` または `SFU` が入る
metadata	string

Publisher オブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	️✔	Publisher の Member id
name	string		Publisher の Member name

Subscription オブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	️✔	Subscription を一意に特定する値
publicationId	string (UUID v4)	️✔	subscribe している Publication の id
subscriber	Subscriber	✔	subscribe している Member の情報

Subscriber オブジェクト

プロパティ	形式	必須	説明
id	string (UUID v4)	️✔	Subscriber の Member id
name	string		Subscriber の Member name

例

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "room": {
      "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc",
      "name": "sample-room",
      "expiresAt": "2025-11-25T12:34:56Z",
      "members": [
        {
          "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3",
          "name": "user01",
          "metadata": "publisher"
        },
        {
          "id": "504ac623-7880-49b5-855f-aa73856ae5e7",
          "name": "user02",
          "metadata": "subscriber"
        }
      ],
      "publications": [
        {
          "id": "aa63b6d1-c1c5-447b-b7ea-faebe70a8b11",
          "contentType": "VIDEO",
          "isEnabled": true,
          "type": "SFU",
          "publisher": {
            "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3",
            "name": "user01"
          }
        },
        {
          "id": "7b213f12-42ba-40f2-9b36-9eb967d263d6",
          "contentType": "DATA",
          "isEnabled": true,
          "type": "P2P",
          "publisher": {
            "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3",
            "name": "user01"
          }
        }
      ],
      "subscriptions": [
        {
          "id": "be35b8dc-bcc3-4005-bf2a-b4d52d51f2db",
          "publicationId": "aa63b6d1-c1c5-447b-b7ea-faebe70a8b11",
          "subscriber": {
            "id": "504ac623-7880-49b5-855f-aa73856ae5e7",
            "name": "user02"
          }
        },
        {
          "id": "4fcef9c1-3f7a-4287-92de-332c2baf3ce6",
          "publicationId": "7b213f12-42ba-40f2-9b36-9eb967d263d6",
          "subscriber": {
            "id": "504ac623-7880-49b5-855f-aa73856ae5e7",
            "name": "user02"
          }
        }
      ]
    }
  }
}

異常系

例 1. Room の name が指定されていない場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": -32602,
    "message": "Parameter must have required property 'name'",
  }
}

closeRoom

id または name で指定した Room を削除します。 id と name の両方が指定された場合は id に基づいて Room を削除します。

リクエストボディ

プロパティ	形式	必須	説明
jsonrpc	string	️✔	`2.0` を指定する
id	string \| integer	✔	任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る
method	string	✔	`closeRoom` を指定する
params	object	✔	Room の id または name を指定する（id あるいは name のいずれかは必須）

params プロパティの構造

プロパティ	形式	必須	説明
id	string (UUID v4)		Room の id を指定する
name	string		Room の name を指定する

例 1. id 6abbecae-dd86-4e8b-ab9f-8da2c7740ddc の Room を削除する場合のリクエストボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "closeRoom",
  "params": {
    "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc"
  }
}

例 2. name sample-room の Room を削除する場合のリクエストボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "closeRoom",
  "params": {
    "name": "sample-room"
  }
}

レスポンスボディ

正常系

レスポンスボディ

プロパティ	形式	必須	説明
jsonrpc	string	️✔	`2.0` が入る
id	string \| integer	✔	リクエストボディで指定した id の値が入る
result	object	✔

例

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {}
}

異常系

例 1. 指定した id の Room が存在しなかった場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": 404,
    "message": "Room '6abbecae-dd86-4e8b-ab9f-8da2c7740ddc' not found"
  }
}

例 2. 指定した name の Room が存在しなかった場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": 404,
    "message": "Room with name 'sample-room' not found"
  }
}

例 3. Room の id および name がどちらも指定されていない場合

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": -32602,
    "message": "'id' or 'name' must be specified",
  },
}

removeMember

id または name で指定した特定の Member を削除します。 id と name の両方が指定された場合は id に基づいて Member を削除します。

リクエストボディ

プロパティ	形式	必須	説明
jsonrpc	string	️✔	`2.0` を指定する
id	string \| integer	✔	任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る
method	string	✔	`removeMember` を指定する
params	object	✔	Room および Member を指定する

params プロパティの構造

プロパティ	形式	必須	説明
room	object	✔	Room の id または name を指定する（id あるいは name のいずれかは必須）

room プロパティの構造

プロパティ	形式	必須	説明
id	string		Room の id を指定する
name	string		Room の name を指定する
member	object	✔	Member の id または name を指定する（id あるいは name のいずれかは必須）

member プロパティの構造

プロパティ	形式	必須	説明
id	string		Member の id を指定する
name	string		Member の name を指定する

例 1. id 6abbecae-dd86-4e8b-ab9f-8da2c7740ddc の Room から、id 1adee02b-811d-4a79-b07d-cdcb1437c7c3 の Member を削除する場合のリクエストボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "removeMember",
  "params": {
    "room": {
      "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc",
      "member": {
        "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3"
      }
    }
  }
}

例 2. id 6abbecae-dd86-4e8b-ab9f-8da2c7740ddc の Room から、name user01 の Member を削除する場合のリクエストボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "removeMember",
  "params": {
    "room": {
      "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc",
      "member": {
        "name": "user01"
      }
    }
  }
}

例 3. name sample-room の Room から、id 1adee02b-811d-4a79-b07d-cdcb1437c7c3 の Member を削除する場合のリクエストボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "removeMember",
  "params": {
    "room": {
      "name": "sample-room",
      "member": {
        "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3"
      }
    }
  }
}

例 4. name sample-room の Room から、name user01 の Member を削除する場合のリクエストボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "removeMember",
  "params": {
    "room": {
      "name": "sample-room",
      "member": {
        "name": "user01"
      }
    }
  }
}

レスポンスボディ

正常系

レスポンスボディ

プロパティ	形式	必須	説明
jsonrpc	string	️✔	`2.0` が入る
id	string \| integer	✔	リクエストボディで指定した id の値が入る
result	object	✔

例

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {}
}

異常系

例 1. 指定した id の Room が存在しなかった場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": 404,
    "message": "Room '6abbecae-dd86-4e8b-ab9f-8da2c7740ddc' not found"
  }
}

例 2. 指定した name の Room が存在しなかった場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": 404,
    "message": "Room with name 'sample-room' not found"
  }
}

例 3. Room の id および name がどちらも指定されていない場合

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": -32602,
    "message": "Room 'id' or 'name' must be specified"
  },
}

例 4. 指定した id の Member が存在しなかった場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": 404,
    "message": "Member '1adee02b-811d-4a79-b07d-cdcb1437c7c3' not found"
  }
}

例 5. 指定した name の Member が存在しなかった場合のレスポンスボディ

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": 404,
    "message": "Member with name 'user01' not found"
  }
}

例 6. Member の id および name がどちらも指定されていない場合

{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "code": -32602,
    "message": "Member 'id' or 'name' must be specified"
  },
}

文字起こし β版

JavaScript SDK