464 lines
12 KiB
Markdown
464 lines
12 KiB
Markdown
# GXRTC服务器API文档
|
||
|
||
## 接口标准定义：
|
||
|
||
### 标准返回JSON 模版：
|
||
|
||
| Key | Value | 说明 |
|
||
| ---- | ----- | ---- |
|
||
| meta | {"code": 400, "message": "params face_img is required"} |
|
||
| code | 参考HTTP status code规范：https://developer.mozilla.org/en-US/docs/Web/HTTP/Status |
|
||
| message | 用于客户端将提示给用户显示|
|
||
| data | {} | map KV结构，key 一定为string,Value可为任意对象，可理解为Golang中的map[string]interface{} |
|
||
|
||
异常返回示例：
|
||
|
||
```bash
|
||
{"meta": {"code": 400, "message": "params face_img is required"}}
|
||
```
|
||
|
||
正常返回结构体参考：
|
||
|
||
```bash
|
||
{
|
||
"meta": {
|
||
"code": 200
|
||
},
|
||
"data": {
|
||
"imgs": [
|
||
"data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0........"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 服务定义：
|
||
- 服务器API根路径：https://meeting.cnsdt.com/api/v1
|
||
- 服务API返回值说明：
|
||
- 服务端所有API Respose返回格式默认为json
|
||
- json结构：
|
||
- 异常返回示例：
|
||
```json
|
||
{
|
||
"meta": {
|
||
"code": 403,
|
||
"error": "user unauthorized",
|
||
"message": "用户没有登录，不能使用"
|
||
}
|
||
}
|
||
```
|
||
- 正常返回示例：
|
||
```json
|
||
{
|
||
"meta": {
|
||
"code": 200
|
||
},
|
||
"data": {
|
||
"rooms": [
|
||
{
|
||
"sid": "RM_44AJticWDN3t",
|
||
"name": "thehome",
|
||
"empty_timeout": 300,
|
||
"departure_timeout": 20,
|
||
"creation_time": 1731684825,
|
||
"turn_password": "3b4QxehgfMm7RvjTjDI75ot22IhMgIrBFeWmSl8NUgyA",
|
||
"enabled_codecs": [
|
||
{
|
||
"mime": "audio/opus"
|
||
},
|
||
{
|
||
"mime": "audio/red"
|
||
},
|
||
{
|
||
"mime": "video/VP8"
|
||
},
|
||
{
|
||
"mime": "video/H264"
|
||
},
|
||
{
|
||
"mime": "video/VP9"
|
||
},
|
||
{
|
||
"mime": "video/AV1"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
|
||
## API: 获取access_token
|
||
|
||
### Request:
|
||
- API Path: `/room/token`
|
||
- Method: `POST`
|
||
- Content Type: `form`
|
||
- Params:
|
||
- uid: `string` 用户ID
|
||
- room: `string` 房间ID
|
||
- Example:
|
||
```bash
|
||
curl -XPOST https://{{API_ROOT}}/api/v1/room/token -d "uid=xtqxk&room=thehome"
|
||
```
|
||
|
||
### Response:
|
||
- Example:
|
||
```json
|
||
{
|
||
"meta": {
|
||
"code": 200
|
||
},
|
||
"data": {
|
||
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3MzE2ODg3OTgsImlzcyI6IkFQSTdaOUNQamhtdVo4eCIsIm5iZiI6MTczMTY4NTE5OCwic3ViIjoieHRxeGsiLCJ2aWRlbyI6eyJyb29tIjoidGhlaG9tZSIsInJvb21Kb2luIjp0cnVlfX0.GfNtz3u7kXQRJ3Rkg4usQOF2uDdJSrXfJmD3aewB-4M"
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
## API: 创建房间
|
||
|
||
### Request:
|
||
- API Path: `/room/`
|
||
- Method: `POST`
|
||
- Content Type: `form`
|
||
- Params:
|
||
- room: `string` 房间ID，目前与名称重叠，未来房间ID会由服务器指定，客户端仅支持传递房间名称
|
||
- Example:
|
||
```bash
|
||
curl -XPOST https://{{API_ROOT}}/api/v1/room/ -d "room=thehome"
|
||
```
|
||
|
||
### Response:
|
||
- Example:
|
||
```json
|
||
{
|
||
"meta": {
|
||
"code": 200
|
||
},
|
||
"data": {
|
||
"sid": "RM_44AJticWDN3t",
|
||
"name": "thehome",
|
||
"empty_timeout": 300,
|
||
"departure_timeout": 20,
|
||
"creation_time": 1731684825,
|
||
"turn_password": "3b4QxehgfMm7RvjTjDI75ot22IhMgIrBFeWmSl8NUgyA",
|
||
"enabled_codecs": [
|
||
{
|
||
"mime": "audio/opus"
|
||
},
|
||
{
|
||
"mime": "audio/red"
|
||
},
|
||
{
|
||
"mime": "video/VP8"
|
||
},
|
||
{
|
||
"mime": "video/H264"
|
||
},
|
||
{
|
||
"mime": "video/VP9"
|
||
},
|
||
{
|
||
"mime": "video/AV1"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
## API: 获取所有房间列表
|
||
|
||
### Request:
|
||
- API Path: `/room/`
|
||
- Method: `GET`
|
||
- Example:
|
||
```bash
|
||
curl -XGET https://{{API_ROOT}}/api/v1/room/
|
||
```
|
||
### Response:
|
||
```json
|
||
{
|
||
"meta": {
|
||
"code": 200
|
||
},
|
||
"data": {
|
||
"rooms": [
|
||
{
|
||
"sid": "RM_44AJticWDN3t",
|
||
"name": "thehome",
|
||
"empty_timeout": 300,
|
||
"departure_timeout": 20,
|
||
"creation_time": 1731684825,
|
||
"turn_password": "3b4QxehgfMm7RvjTjDI75ot22IhMgIrBFeWmSl8NUgyA",
|
||
"enabled_codecs": [
|
||
{
|
||
"mime": "audio/opus"
|
||
},
|
||
{
|
||
"mime": "audio/red"
|
||
},
|
||
{
|
||
"mime": "video/VP8"
|
||
},
|
||
{
|
||
"mime": "video/H264"
|
||
},
|
||
{
|
||
"mime": "video/VP9"
|
||
},
|
||
{
|
||
"mime": "video/AV1"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
|
||
## API: 解散房间
|
||
|
||
### Request:
|
||
- API Path: `/room/{{room}}`
|
||
- Method: `DELETE`
|
||
- Params:
|
||
- room: `string` 房间ID，目前与名称重叠，未来房间ID会由服务器指定，客户端仅支持传递房间名称
|
||
- Example:
|
||
```bash
|
||
curl -XDELETE https://{{API_ROOT}}/api/v1/room/thehome
|
||
```
|
||
|
||
### Response:
|
||
- Example:
|
||
成功返回被删除的房音详情
|
||
```json
|
||
{
|
||
"meta": {
|
||
"code": 200
|
||
},
|
||
"data": {
|
||
"sid": "RM_44AJticWDN3t",
|
||
"name": "thehome",
|
||
"empty_timeout": 300,
|
||
"departure_timeout": 20,
|
||
"creation_time": 1731684825,
|
||
"turn_password": "3b4QxehgfMm7RvjTjDI75ot22IhMgIrBFeWmSl8NUgyA",
|
||
"enabled_codecs": [
|
||
{
|
||
"mime": "audio/opus"
|
||
},
|
||
{
|
||
"mime": "audio/red"
|
||
},
|
||
{
|
||
"mime": "video/VP8"
|
||
},
|
||
{
|
||
"mime": "video/H264"
|
||
},
|
||
{
|
||
"mime": "video/VP9"
|
||
},
|
||
{
|
||
"mime": "video/AV1"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
失败返回错误信息，如房间不存在，或没有权限等
|
||
|
||
## API: 获取房间参与者列表
|
||
|
||
### Request:
|
||
- API Path: `/room/{{room}}/participants`
|
||
- Method: `GET`
|
||
- Params:
|
||
- room: `string` 房间ID
|
||
- Example:
|
||
```bash
|
||
curl -XGET https://{{API_ROOT}}/api/v1/room/{{room}}/participants
|
||
```
|
||
|
||
### Response:
|
||
- Example:
|
||
```json
|
||
{
|
||
"meta": {
|
||
"code": 200
|
||
},
|
||
"data": {
|
||
"participants": [
|
||
{
|
||
"sid": "user1",
|
||
"name": "Alice",
|
||
"joined_at": 1731684825,
|
||
"...":"..."
|
||
},
|
||
{
|
||
"sid": "user2",
|
||
"name": "Bob",
|
||
"joined_at": 1731684830,
|
||
"...":"..."
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
- participants: `[]ParticipantInfo`, 返回[ParticipantInfo](structs.md#ParticipantInfo)列表
|
||
|
||
## API: 从房间中移除参与者
|
||
|
||
### Request:
|
||
- API Path: `/room/{{room}}/participant/{{uid}}`
|
||
- Method: `DELETE`
|
||
- Params:
|
||
- room: `string` 房间ID
|
||
- uid: `string` 用户ID
|
||
- Example:
|
||
```bash
|
||
curl -XDELETE https://{{API_ROOT}}/api/v1/room/{{room}}/participant/{{uid}}
|
||
```
|
||
|
||
### Response:
|
||
- Example:
|
||
当成功时，失败时code不为200
|
||
```json
|
||
{
|
||
"meta": {
|
||
"code": 200
|
||
}
|
||
}
|
||
```
|
||
|
||
## API: 获取房间中指定用户的详情
|
||
|
||
### Request:
|
||
- API Path: `/room/{{room}}/participant/{{uid}}`
|
||
- Method: `GET`
|
||
- Params:
|
||
- room: `string` 房间ID
|
||
- uid: `string` 用户ID
|
||
- Example:
|
||
```bash
|
||
curl -XGET https://{{API_ROOT}}/api/v1/room/{{room}}/participant/{{uid}}
|
||
```
|
||
|
||
|
||
### Response:
|
||
- Example:
|
||
```json
|
||
{
|
||
"meta": {
|
||
"code": 200
|
||
},
|
||
"data": { // ParticipantInfo
|
||
"sid": "user1",
|
||
"name": "Alice",
|
||
"joined_at": 1731684825,
|
||
"...":"..."
|
||
}
|
||
}
|
||
```
|
||
- data : `ParticipantInfo`, 返回[ParticipantInfo](structs.md#ParticipantInfo)
|
||
|
||
|
||
## API: 将房间中的用户禁音/解禁
|
||
|
||
### Request:
|
||
- API Path: `/room/{{room}}/participant/{{uid}}/mute`
|
||
- Method: `POST/DELETE`, POST:禁音，DELETE解禁
|
||
- Params:
|
||
- room: `string` 房间ID
|
||
- uid: `string` 用户ID
|
||
- Example:
|
||
```bash
|
||
curl -XPOST https://{{API_ROOT}}/api/v1/room/{{room}}/participant/{{uid}}/mute
|
||
```
|
||
|
||
### Response:
|
||
- Example:
|
||
当成功时，失败时code不为200
|
||
```json
|
||
{
|
||
"meta": {
|
||
"code": 200
|
||
}
|
||
}
|
||
```
|
||
|
||
## API: 更新房间中的用户信息
|
||
|
||
### Request:
|
||
- API Path: `/room/{{room}}/participant/{{uid}}/info`
|
||
- Method: `POST`
|
||
- Params:
|
||
- room: `string` 房间ID
|
||
- uid: `string` 用户ID
|
||
- Form:
|
||
- attrs: `string`, json 格式的key,value结构，如：{"nickname":"rick","gender":"male"}
|
||
- metadata: `string`, 任意格式的字符串
|
||
|
||
- Example:
|
||
```bash
|
||
curl -XPOST https://{{API_ROOT}}/api/v1/room/{{room}}/participant/{{uid}}/info -d "metadata=metadata_string&attrs=%7B%22nickname%22%3A%22rick%22%2C%22gender%22%3A%22male%22%7D"
|
||
```
|
||
|
||
|
||
### Response:
|
||
- Example:
|
||
```json
|
||
{
|
||
"meta": {
|
||
"code": 200
|
||
},
|
||
"data": { // ParticipantInfo
|
||
"sid": "user1",
|
||
"name": "Alice",
|
||
"joined_at": 1731684825,
|
||
"...":"..."
|
||
}
|
||
}
|
||
```
|
||
- data : `ParticipantInfo`, 返回[ParticipantInfo](structs.md#ParticipantInfo)
|
||
|
||
|
||
## API: 更新房间中的用户权限
|
||
|
||
### Request:
|
||
- API Path: `/room/{{room}}/participant/{{uid}}/permissions`
|
||
- Method: `POST`
|
||
- Params:
|
||
- room: `string` 房间ID
|
||
- uid: `string` 用户ID
|
||
- Form:
|
||
- permission: `string`, json 格式的key,value结构，permission结构体参考：[permission](structs.md#participantpermission)
|
||
|
||
- Example:
|
||
```bash
|
||
curl -XPOST https://{{API_ROOT}}/api/v1/room/{{room}}/participant/{{uid}}/info -d "permission="%7B%22can_subscribe%22%3Atrue%2C%22can_publish%22%3Afalse%7D""
|
||
```
|
||
|
||
|
||
### Response:
|
||
- Example:
|
||
```json
|
||
{
|
||
"meta": {
|
||
"code": 200
|
||
},
|
||
"data": { // ParticipantInfo
|
||
"sid": "user1",
|
||
"name": "Alice",
|
||
"joined_at": 1731684825,
|
||
"...":"..."
|
||
}
|
||
}
|
||
```
|
||
- data : `ParticipantInfo`, 返回[ParticipantInfo](structs.md#ParticipantInfo)
|