7.2. 服务器 API 参考文档

7.2.1. 更新历史

2016年8月15日 V0.4

  • 增加项目管理接口 /v0.4/project/detail/v0.4/project/update/v0.4/project/reset/v0.4/project/delete,可以使用 API KeyAPI Secret 修改项目了。
  • DELETE /v0.4/sessions/{session_id} 接口成功状态码改为200,添加JSON消息体 {"delete": 1}
  • DELETE /v0.4/tokens/{token_id} 接口成功状态码改为200,添加JSON消息体 {"delete": 1}

2016年4月5日 V0.3

  • 增加录制接口 /v0.3/records,使用Token主键Id可以录制视频。

2015年10月25日 V0.2

  • 获取列表接口支持分页。
  • 支持永久Session和Token类型,新增修改、删除 Session接口, 获取、修改、删除 Token接口, 分类获取永久或非永久的 Session、Token列表接口。
  • GET /v0.2/sessions 返回结果分页表示,每个Session对象添加属性 persistentdatatime_createdlive_daysexpire_in
  • `POST /v0.2/sessions 增加参数 persistentdatalive_days,返回对象添加属性 persistentdatatime_createdlive_daysexpire_in
  • POST /v0.2/tokens 接口废弃, 用新接口 POST /v0.2/sessions/{session_id}/tokens 代替。

2015年9月15日 V0.1

  • 最初上线的版本,提供基本的Session,Token管理功能。

7.2.2. 服务器 API V0.4 接口列表

7.2.2.1. Project(项目)

URL Method Function
/v0.4/project/detail GET 获取此项目信息
/v0.4/project/update PATCH 更新此项目
/v0.4/project/delete DELETE 删除此项目
/v0.4/project/reset POST 重置此项目API Secret

7.2.2.2. Session(会话)

URL Method Function
/v0.4/sessions GET 获取Session列表
/v0.4/sessions POST 创建一个Session
/v0.4/sessions/permanent GET 获取永久Session列表
/v0.4/sessions/nonpermanent GET 获取临时Session列表
/v0.4/sessions/{session_id} GET 获取一个Session的信息
/v0.4/sessions/{session_id} PATCH 修改一个Session
/v0.4/sessions/{session_id} DELETE 删除一个Session

7.2.2.3. Token(令牌)

URL Method Function
/v0.4/sessions/{session_id}/tokens GET 获取session_id下Token列表
/v0.4/sessions/{session_id}/tokens POST 创建一个session_id下的Token
/v0.4/sessions/{session_id}/tokens/permanent GET 获取session_id下永久Token列表
/v0.4/sessions/{session_id}/tokens/nonpermanent GET 获取session_id下临时Token列表
/v0.4/tokens/{token_id} GET 获取一个Token的信息
/v0.4/tokens/{token_id} PATCH 修改一个Token
/v0.4/tokens/{token_id} DELETE 删除一个Token

7.2.2.4. 录制

*目前录制功能处于开发阶段,接口还在修改中,请勿用于生产环境*

URL Method Function
/v0.4/records GET 获取录制纪录列表
/v0.4/records POST 开始/停止录像
/v0.4/records/{record_id} GET 获取一个录像记录的信息
/v0.4/records/{record_id} PATCH 修改一个录像记录

7.2.3. 服务器 API 参考

7.2.3.1. 获取此项目信息

地址: https://api.realtimecat.com:443/v0.4/project/detail

方法: GET

参数: 无

返回:

200 OK

{
    "uuid": "项目主键Id",
    "user_id": "所有者主键Id",
    "name": "项目名",
    "memo": "项目描述",
    "enable": "是否启用",
    "enable_relay": "是否开启rel模式",
    "api_key": "API Key",
    "secret": "API Secret",
    "time_created": "创建时间"
}

7.2.3.2. 更新此项目

地址: https://api.realtimecat.com:443/v0.4/project/update

方法: PATCH

参数:

参数 类型 必填 说明
name string 项目名,长度为50,默认为空
memo boolean 项目描述,长度为1024,默认为空

返回:

200 OK

{
    "uuid": "项目主键Id",
    "user_id": "所有者主键Id",
    "name": "项目名",
    "memo": "项目备注",
    "enable": "是否启用",
    "enable_relay": "是否开启rel模式",
    "api_key": "API Key",
    "secret": "API Secret",
    "time_created": "创建时间"
}

7.2.3.3. 删除此项目信息

地址: https://api.realtimecat.com:443/v0.4/project/delete

方法: DELETE

参数: 无

返回:

200 OK

{
    "delete": "1"
}

7.2.3.4. 重置此项目API Secret

地址: https://api.realtimecat.com:443/v0.4/project/reset

方法: POST

参数: 无

返回:

200 OK

{
    "uuid": "项目主键Id",
    "user_id": "所有者主键Id",
    "name": "项目名",
    "memo": "项目备注",
    "enable": "是否启用",
    "enable_relay": "是否开启rel模式",
    "api_key": "API Key",
    "secret": "修改后的API Secret",
    "time_created": "创建时间"
}

7.2.3.5. 获取Session列表

地址: https://api.realtimecat.com/v0.4/sessions

方法: GET

参数:

参数 类型 必填 说明
page string 页数, URL参数
page_size string 每页大小,URL参数,最大为100,默认为25

返回:

200 OK

{
    "page": "当前页数",
    "page_size": "每页数量",
    "count": "总数",
    "next": "下一页地址",
    "previous": "上一页地址",
    "results": [{
        "uuid": "主键Id",
        "label": "标签",
        "type": "类型",
        "permanent": "是否持久化",
        "data": "定义数据",
        "time_created": "创建时间",
        "live_days": "存活天数",
        "expire_in": "过期时间"
        },//每页25条Session信息]
}

7.2.3.6. 创建一个Session

地址: https://api.realtimecat.com/v0.4/sessions

方法: POST

参数:

参数 类型 必填 说明
type string 类型,仅可以为p2prel
label string 标签,长度为255,默认为空
permanent boolean 持久化,默认为false,设为true时Session永不过期
data string 自定义数据,长度为1024
live_days integer 存活天数,单位为天,超过时间则Session过期,默认为30天

返回:

201 Created

{
    "uuid": "主键Id",
    "label": "标签",
    "type": "类型",
    "permanent": "是否持久化",
    "data": "自定义数据",
    "time_created": "创建时间",
    "live_days": "存活天数",
    "expire_in": "过期时间"
}

7.2.3.7. 获取永久Session列表

地址: https://api.realtimecat.com/v0.4/sessions/permanent

方法: GET

参数:

参数 类型 必填 说明
page string 页数, URL参数
page_size string 每页大小,URL参数,最大为100,默认为25

返回:

200 OK

{
    "page": "当前页数",
    "page_size": "每页数量",
    "count": "总数",
    "next": "下一页地址",
    "previous": "上一页地址",
    "results": [{
        "uuid": "主键Id",
        "label": "标签",
        "type": "类型",
        "permanent": "是否持久化",
        "data": "定义数据",
        "time_created": "创建时间",
        "live_days": "存活天数",
        "expire_in": "过期时间"
        },//每页25条Session信息]
}

7.2.3.8. 获取临时Session列表

地址: https://api.realtimecat.com/v0.4/sessions/nonpermanent

方法: GET

参数:

参数 类型 必填 说明
page string 页数, URL参数
page_size string 每页大小,URL参数,最大为100,默认为25

返回:

200 OK

{
    "page": "当前页数",
    "page_size": "每页数量",
    "count": "总数",
    "next": "下一页地址",
    "previous": "上一页地址",
    "results": [{
        "uuid": "主键Id",
        "label": "标签",
        "type": "类型",
        "permanent": "是否持久化",
        "data": "定义数据",
        "time_created": "创建时间",
        "live_days": "存活天数",
        "expire_in": "过期时间"
        },//每页25条Session信息]
}

7.2.3.9. 获取一个Session的信息

地址: https://api.realtimecat.com/v0.4/sessions/{session_id}

方法: GET

参数:

参数 类型 必填 说明
session_id string Session主键Id(替换url中{session_id})

返回:

200 OK

{
    "uuid": "主键Id",
    "label": "标签",
    "type": "类型",
    "permanent": "是否持久化",
    "data": "自定义数据",
    "time_created": "创建时间",
    "live_days": "存活天数",
    "expire_in": "过期时间"
}

7.2.3.10. 修改一个Session

地址: https://api.realtimecat.com/v0.4/sessions/{session_id}

方法: PATCH

参数:

参数 类型 必填 说明
session_id string Session主键Id (替换url中{session_id})
label string 标签,长度为255,默认为空
permanent boolean 持久化,默认为false,设为true时Session永不过期
data string 自定义数据,长度为1024
live_days integer 存活天数,单位为天,超过时间则Session过期,默认为30天

返回:

200 OK

{
    "uuid": "主键Id",
    "label": "标签",
    "type": "类型",
    "permanent": "是否持久化",
    "data": "自定义数据",
    "time_created": "创建时间",
    "live_days": "存活天数",
    "expire_in": "过期时间"
}

7.2.3.11. 删除一个Session

地址: https://api.realtimecat.com/v0.4/sessions/{session_id}

方法: DELETE

参数:

参数 类型 必填 说明
session_id string Session主键Id (替换url中{session_id})

返回:

200 OK

{
  "delete": 1
}

7.2.3.12. 获取session_id下Token列表

地址: https://api.realtimecat.com/v0.4/sessions/{session_id}/tokens

方法: GET

参数:

参数 类型 必填 说明
session_id string Session主键Id (替换url中{session_id})
page_size string 每页大小,URL参数,最大为100,默认为25
page string 页数, URL参数

返回:

200 OK

{
    "page": "当前页数",
    "page_size": "每页数量",
    "count": "总数",
    "next": "下一页地址",
    "previous": "上一页地址",
    "results": [{
        "uuid": "主键Id",
        "label": "标签",
        "type": "类型",
        "permanent": "是否持久化",
        "data": "定义数据",
        "time_created": "创建时间",
        "live_days": "存活天数",
        "expire_in": "过期时间"
        },//每页25条Session信息]
}

7.2.3.13. 创建一个session_id下的Token

地址: https://api.realtimecat.com/v0.4/sessions/{session_id}/tokens

方法: POST

参数:

参数 类型 必填 说明
session_id string Session主键Id (替换url中{session_id})
type string 类型,仅可以为pub(发布者)或``sub``(接收者),参见` <>`__
label string 标签,长度为255,默认为空
permanent boolean 持久化,默认为false,设为true时Session永不过期
data string 自定义数据,长度为1024
live_days integer 存活天数,单位为天,超过时间则Session过期,默认为15天
number integer 个数,一次可创建多个Token,最多为10,留空则创建一个

返回:

201 CREATED

{
    "uuid": "主键Id",
    "session_id": "Token所属Session的Id",
    "label": "标签",
    "type": "类型",
    "permanent": "是否持久化",
    "data": "自定义数据",
    "time_created": "创建时间",
    "live_days": "存活天数",
    "expire_in": "过期时间"
}
//当number大于1时返回数组形式的多个Token信息

7.2.3.14. 获取session_id下永久Token列表

地址: https://api.realtimecat.com/v0.4/sessions/{session_id}/tokens/permanent

方法: GET

参数:

参数 类型 必填 说明
session_id string Session主键Id (替换url中{session_id})
page_size string 每页大小,URL参数,最大为100,默认为25
page string 页数, URL参数

返回:

200 OK

{
    "page": "当前页数",
    "page_size": "每页数量",
    "count": "总数",
    "next": "下一页地址",
    "previous": "上一页地址",
    "results": [{
        "uuid": "主键Id",
        "session": "Token所属Session的Id",
        "label": "标签",
        "type": "类型",
        "permanent": "是否持久化",
        "data": "定义数据",
        "time_created": "创建时间",
        "live_days": "存活天数",
        "expire_in": "过期时间"
        },//每页25条Session信息]
}

7.2.3.15. 获取session_id下临时Token列表

地址: https://api.realtimecat.com/v0.4/sessions/{session_id}/tokens/nonpermanent

方法: GET

参数:

参数 类型 必填 说明
session_id string Session主键Id (替换url中{session_id})
page_size string 每页大小,URL参数,最大为100,默认为25
page string 页数, URL参数

返回:

200 OK

{
    "page": "当前页数",
    "page_size": "每页数量",
    "count": "总数",
    "next": "下一页地址",
    "previous": "上一页地址",
    "results": [{
        "uuid": "主键Id",
        "session": "Token所属Session的Id",
        "label": "标签",
        "type": "类型",
        "permanent": "是否持久化",
        "data": "定义数据",
        "time_created": "创建时间",
        "live_days": "存活天数",
        "expire_in": "过期时间"
        },//每页25条Session信息]
}

7.2.3.16. 获取一个Token的信息

地址: https://api.realtimecat.com/v0.4/tokens/{token_id}

方法: GET

参数:

参数 类型 必填 说明
token_id string Token主键Id (替换url中{token_id})

返回:

200 OK

{
    "uuid": "主键Id",
    "session_id": "Token所属Session的Id",
    "label": "标签",
    "type": "类型",
    "permanent": "是否持久化",
    "data": "自定义数据",
    "time_created": "创建时间",
    "live_days": "存活天数",
    "expire_in": "过期时间"
}

7.2.3.17. 修改一个Token

地址: https://api.realtimecat.com/v0.4/tokens/{token_id}

方法: PATCH

参数:

参数 类型 必填 说明
token_id string Token主键Id (替换url中{token_id})
label string 标签,长度为255,默认为空
permanent boolean 持久化,默认为false,设为true时Session永不过期
data string 自定义数据,长度为1024
live_days integer 存活天数,单位为天,超过时间则Session过期,默认为15天

返回:

200 OK

{
    "uuid": "主键Id",
    "session_id": "Token所属Session的Id",
    "label": "标签",
    "type": "类型",
    "permanent": "是否持久化",
    "data": "自定义数据",
    "time_created": "创建时间",
    "live_days": "存活天数",
    "expire_in": "过期时间"
}

7.2.3.18. 删除一个Token

地址: https://api.realtimecat.com/v0.4/tokens/{token_id}

方法: DELETE

参数:

参数 类型 必填 说明
token_id string Token主键Id (替换url中{token_id})

返回:

200 OK

{
  "delete": 1
}

7.2.3.19. 获取录制纪录列表

*目前处于测试阶段,接口可能不稳定,请勿用于生产环境*

地址: https://api.realtimecat.com/v0.4/records

方法: GET

参数:

参数 类型 必填 说明
page_size string 每页大小,URL参数,最大为100,默认为25
page string 页数, URL参数

返回:

200 OK

{
    "page": "当前页数",
    "page_size": "每页数量",
    "count": "总数",
    "next": "下一页地址",
    "previous": "上一页地址",
    "results":[{
        "uuid": "主键Id",
        "video_start": "视频开始时间,例如'2016-02-04T08:10:20.296000', 当`status`为`recording`时为`null`",
        "video_stop": "视频停止时间, 例如'2016-02-04T08:10:23.998542', 当`status`为`recording`时为`null`",
        "video_length": "视频长度, 单位秒",
        "video_type": "视频类型, 默认为mp4",
        "time_created": "创建时间",
        "label": "标签",
        "project": "当前的项目Id",
        "session": "当前的SessionId",
        "token": "当前的Token",
        "channel": "当前的视频流",
        "action": "操作,`start`或`stop`",
        "status": "视频状态, `recording`或`done`",
        "url": "视频的链接, 当`status`为`recording`时为null"
        },//每页25条Session信息]
}

7.2.3.20. 开始/停止录像

*目前处于测试阶段,接口可能不稳定,请勿用于生产环境*

地址: https://api.realtimecat.com/v0.4/records``

方法: POST

参数:

参数 类型 必填 说明
token string Token主键Id
channel string 视频流Id
action string 操作, startstop
type string 视频类型, mp4webm
label string 标签

返回:

200 OK

{
    "uuid":"主键Id",
    "video_start": "视频开始时间,例如’2016-02-04T08:10:20.296000’, 当`status`为`recording`时为`null`",
    "video_stop": "视频停止时间, 例如‘2016-02-04T08:10:23.998542’, 当`status`为`recording`时为`null`",
    "video_length": "视频长度, 单位秒, 当`action`为`start`时为null",
    "video_type": "视频类型, 默认为mp4",
    "time_created": "创建时间",
    "label": "标签",
    "project": "当前的项目Id",
    "session": "当前的SessionId",
    "token": "当前的Token",
    "channel": "当前的视频流",
    "action": "操作,`start`或`stop`",
    "status": "视频状态, 当`status`为`recording`时为null",
    "url": "视频的链接"
}

7.2.3.21. 获取一个录像记录的信息

*目前处于测试阶段,接口可能不稳定,请勿用于生产环境*

地址: https://api.realtimecat.com/v0.4/records/{record_id}

方法: GET

参数:

参数 类型 必填 说明
record_id string 录像记录主键Id (替换url中{record_id})

返回:

200 OK

{
    "uuid": "主键Id",
    "video_start": "视频开始时间,例如‘2016-02-04T08:10:20.296000’, 当`status`为`recording`时为`null`",
    "video_stop": "视频停止时间, 例如’2016-02-04T08:10:23.998542‘, 当`status`为`recording`时为`null`",
    "video_length": "视频长度, 单位秒, 当`action`为`start`时为null",
    "video_type": "视频类型, 默认为mp4",
    "time_created": "创建时间",
    "label": "标签",
    "project": "当前的项目Id",
    "session": "当前的SessionId",
    "token": "当前的Token",
    "channel": "当前的视频流",
    "action": "操作,`start`或`stop`",
    "status": "视频状态, 当`status`为`recording`时为null",
    "url": "视频的链接"
}

7.2.3.22. 更新一个录像记录

*目前处于测试阶段,接口可能不稳定,请勿用于生产环境*

地址: https://api.realtimecat.com/v0.4/records/{record_id}

方法: PATCH

参数:

参数 类型 必填 说明
record_id string 录像记录主键Id (替换url中{record_id})
label string 标签

返回:

200 OK

{
    "uuid": "主键Id",
    "video_start": "视频开始时间,例如‘2016-02-04T08:10:20.296000’, 当`status`为`recording`时为`null`",
    "video_stop": "视频停止时间, 例如’2016-02-04T08:10:23.998542‘, 当`status`为`recording`时为`null`",
    "video_length": "视频长度, 单位秒, 当`action`为`start`时为null",
    "video_type": "视频类型, 默认为mp4",
    "time_created": "创建时间",
    "label": "标签",
    "project": "当前的项目Id",
    "session": "当前的SessionId",
    "token": "当前的Token",
    "channel": "当前的视频流",
    "action": "操作,`start`或`stop`",
    "status": "视频状态, 当`status`为`recording`时为null",
    "url": "视频的链接"
}

7.2.4. 示例

我们以Node.js为例展示如何调用我们的服务器端API

创建Session

     // 引入依赖的模块
     var https = require('https');
     var querystring = require('querystring');

      // 设置session类型,此处以p2p为例
     var postData = querystring.stringify({
                 "type": "p2p"
     });

     // 设置请求地址
     // 在headers中加入X-RTCAT-APIKEY和X-RTCAT-SECRET
     var options = {
         hostname: 'api.realtimecat.com',
         port: 443,
         path: '/v0.1/sessions',
         method: 'POST',
         headers: {
             'Content-Type': 'application/x-www-form-urlencoded',
             'Content-Length': postData.length,
             'X-RTCAT-APIKEY': '1234567890abcdefghijklmnopqrstuv',
             'X-RTCAT-SECRET': '1234567890abcdefghijklmnopqrstuv'
         }
     };

     var myReq = https.request(options, function (response) {
         console.log('STATUS: ' + response.statusCode);
         console.log('HEADERS: ' + JSON.stringify(response.headers));
         response.setEncoding('utf8');
         response.on('data', function (chunk) {
             console.log('BODY: ' + chunk);
             var session = JSON.parse(chunk);
             // 服务器端返回session_id,以下为回调函数
             ...

         });
     });

     myReq.on('error', function (error) {
         console.dir('problem with request: ' + error.message);
     });

     // write data to request body
     myReq.write(postData);
     myReq.end()

生成一个新Token

     // 使用您的session_id以及创建的用户角色,此处以发布者(pub)为例
     var postData = querystring.stringify({
         "session_id": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqrstuvwxyz",
         "type": "pub"
     });

     // 设置请求地址
     // 在headers中加入X-RTCAT-APIKEY和X-RTCAT-SECRET
     var options = {
         hostname: 'api.realtimecat.com',
         port: 443,
         path: '/v0.1/tokens',
         method: 'POST',
         headers: {
             'Content-Type': 'application/x-www-form-urlencoded',
             'Content-Length': postData.length,
             'X-RTCAT-APIKEY': '1234567890abcdefghijklmnopqrstuv',
             'X-RTCAT-SECRET': '1234567890abcdefghijklmnopqrstuv'
         }
     };

     // 向服务器端发出请求
     var myReq = https.request(options, function (response) {
         console.log('STATUS: ' + response.statusCode);
         console.log('HEADERS: ' + JSON.stringify(response.headers));
         response.setEncoding('utf8');
         response.on('data', function (chunk) {
             console.log('BODY: ' + chunk);
             var response = JSON.parse(chunk);
             // 服务器端返回了token,此时response形如{token: "1234567890abcdefghijklmnopqrstuvwxyz"}
             // 在这里进行接下来的处理
             ...

         });
     });

     myReq.on('error', function (error) {
         console.dir('problem with request: ' + error.message);
     });

     // write data to request body
     myReq.write(postData);
     myReq.end();