7.1. 服务器 API 介绍

7.1.1. 简介

通过调用实时猫服务器端API,可以管理 项目、创建和修改 Session, Token,进行视频录制等。

7.1.2. 风格、协议和调用地址

服务器端API符合RESTful API风格,使用任何后端开发语言,通过发送 HTTP Request 请求 即可调用。

服务器API的调用根地址为:

https://api.realtimecat.com/

不同版本API以版本号 v<major.minor> 区分,例如 https://api.realtimecat.com/v0.4 。 不同版本API共享数据对象,例如在v0.3下修改了某Session,在v0.4下获取此Session将是修改后的状态。

当某一版本API发布后,其中包含的接口将保持不变,新版本出现的新接口会提供更多功能,而新版本中的原接口可能修正一些潜在问题,并尽量保持调用参数和返回对象不变,强烈建议使用最新版本的API。

警告

所有API调用接口地址均不含结尾斜杠 /

警告

如果遇到服务器证书错误,例如使用旧版本java时会发生 sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target 错误,请更新JDK至 8u101 或更新版本,其他语言请手动添加证书信任。

7.1.3. 身份验证(Authentication)

在实时猫开发者控制台中创建项目后,可以查看到项目的 API keyAPI secret ,任何服务器端API的调用都需要在 HTTP Request 请求头信息 Header 中,发送以下项目信息进行验证:

X-RTCAT-APIKEY: API key
X-RTCAT-SECRET: API secret

例如,在Linux终端下使用 curl 创建一个Session:

curl -X POST \
     -d "type=p2p" \
     -H "X-RTCAT-APIKEY: 00000000-0000-0000-0000-000000000000" \
     -H "X-RTCAT-SECRET: FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF" \
     https://api.realtimecat.com:443/v0.4/sessions

返回:

{"uuid":"01234567-89ab-cdef-0123-456789abcdef","label":null,"type":"p2p","permanent":false,"data":null,"time_created":"2016-08-18T02:24:16.437816Z","live_days":30,"expire_in":"2016-09-17T02:24:16.437Z"}

注解

不同开发语言,不同的HTTP库下添加Header的方法不同,请根据具体情况使用。

注解

本质上,实时猫开发者控制台中管理 SessionToken ,就是在调用相应的服务器端API。

7.1.4. 返回值和错误返回

服务器端API调用后的返回的状态码为``2xx``时API调用成功,``4xx``时调用失败,这两种情况下返回的消息体都是可以被解析为JSON对象的字符串(状态码为``204``时无消息体)。

失败时的返回JSON对象如下:

{
    "error": "错误代码",
    "description": "错误描述"
}

比如,

Response Code: 401 Unauthorized

Response Body:

{
    "error": "RTCAT-ERROR-101",
    "description": "无效的验证头信息。请传入X-RTCAT-APIKEY和X-RTCAT-SECRET。"
}

注解

返回消息体的编码

返回的消息体的默认编码格式为utf-8,当某些客户端不能自动识别时,会出现中文乱码的情况,你可以在请求的 头信息 中手动添加 Accept: application/json; charset=utf-8 来让返回的消息头带有 Content-Type: application/json; charset=utf-8 的编码标识,从而让客户端自动解码为utf-8。

注解

调用失败时的调试

  1. 首先查看返回的错误代码,并进行相应处理。常见的错误包括:错误的调用地址,HTTP Request Header 格式错误,未指定或错误指定了 APIKeySecret,以及调用参数不全。
  2. 尝试使用线上 HTTP Request 工具,如 hurl.it ,测试调用效果。
  3. 如果通过调用成功获得了 SessionToken ,但未能成功连接,需要优先检查 SessionToken 的类型 Type 是否正确。
  4. 如果仍然无法解决问题,请 联系我们/获取支持

7.1.5. 版本和更新

目前服务器API的版本号为 v0.4

    0.4 新版功能:
  1. 新增了项目管理接口。

    在 0.4 版更改:
  1. DELETE 方法的返回状态码改为200, 返回JSON对象消息体。

    0.3 新版功能:
  1. 新增了仅用于测试的服务器视频录制接口。

    在 0.3 版更改:
  1. 所有 persistent 相关接口,现已重命名为 permanent

  2. 所有单数形式的 token 相关接口,现已重命名为复数 tokens