科达视讯平台API使用说明

1 概述

    科达视讯平台API，主要为希望对视频会议进行二次开发的开发者提供一套完整的接口。
    API接口基于HTTP协议，采用RESTful 的设计风格。
    包括以下API：
        统一登陆：提供软件权限校验、用户账户登录及登陆保活接口
        会议管理：提供视频会议创建、预约及公共、个人会议模板的相关接口
        会议控制：提供视频会议中的与会方管理、画面合成、混音、电视墙等相关功能的接口
        网管系统：提供设备、告警、统计信息查询的相关接口
        录播系统：提供对录播服务器录像室、直播室、节目列表创建、查询、修改的相关接口
        会议信息推送：提供视频会议中与会方、画面合成、混音、电视墙等状态变化的反向推送功能

2 整体风格

2.1 URI风格

URI请求风格为：

http://{domain|ip}/api/{version}/{app}/{resources}/{rc_id}

    备注：version = v1
              app分类为：
                 1. system 统一登陆
                 2. mc 会议管理
                 3. vc 会议控制
                 4. nms 网管系统
                 5. vrs 录播系统
                 6. publish 推送

2.2 时间格式

采用ISO8601:2000标准

2016-11-11T15:30:00+08:00

2.3 HTTP请求类型

    GET（SELECT）：从服务器取出资源（一项或多项）。
    POST（CREATE）：在服务器新建一个资源。
    PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
    DELETE（DELETE）：从服务器删除资源。

3 使用说明

3.1 登录

    科达视讯平台API采用统一登陆方式对软件权限及用户账户进行验证，使用者仅需登陆一次，便可调用各子系统的API。
    使用者需先申请一个API License，并导入到科达视频会议系统中，其中包含软件key和密钥。
    通过软件key+密钥向平台注册获取account_token

POST /api/v1/system/token HTTP/1.1
Accept-Encoding: identity
Content-Length: 58
Host: 127.0.0.1
User-Agent: Python-urllib/3.5
Content-Type: application/x-www-form-urlencoded
Connection: close

oauth_consumer_key=key&oauth_consumer_secret=12345678

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 27 Jun 2016 07:39:49 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 67
Connection: close

{"success": 1, "account_token": "6567e24b425db665a3044db69f0c6fe4"}

二次开发通过account_token + 帐号 + 密码登录

POST /api/v1/system/login HTTP/1.1
Accept-Encoding: identity
Content-Length: 85
Host: 172.16.185.146
User-Agent: Python-urllib/3.5
Content-Type: application/x-www-form-urlencoded
Connection: close
password=888888&username=name&account_token=6567e24b425db665a3044db69f0c6fe4

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 27 Jun 2016 07:39:49 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 43
Connection: close
Set-Cookie: SSO_COOKIE_KEY=890db118-9033-4317-8fe5-7456913d5793;
Expires=Mon, 11-Jul-2016 07:39:49 GMT; 

{"success": 1, "username": "0512110001003"}

    平台回复会将登录信息写入cookies中。
    后续请求，二次开发者需要在每次请求的时候携带account_token+cookies来进行操作。
    对于客户端无法自动处理cookie的，需要将登录的cookie保存起来，后续请求通过设置Http的Cookie字段，手动设置
    平台会验证开发者权限以及用户权限。
    每次请求会刷新token存活时间，若无操作，开发者需要自行调用接口刷新token存活时间。

3.2 获取类请求

参数平铺跟在URI后面，以&区分多参数
范例（获取会议列表为例）

GET /api/v1/vc/confs?account_token=6567e24b425db665a3044db69f0c6fe4 HTTP/1.1
Accept-Encoding: identity
User-Agent: Python-urllib/3.5
Host: 127.0.0.1
Cookie: SSO_COOKIE_KEY=890db118-9033-4317-8fe5-7456913d5793
Connection: close

3.3 修改类请求（POST PUT）

参数以表单形式提交，字符编码utf-8

Content-Type: application/x-www-form-urlencoded;charset=utf-8;

json类参数，以params作为key，json内容urlencoder后作为value进行传递。
范例（添加终端为例）

POST /api/v1/vc/confs/1118986/mts HTTP/1.1
Accept-Encoding: identity
User-Agent: Python-urllib/3.5
Cookie: SSO_COOKIE_KEY=890db118-9033-4317-8fe5-7456913d5793
Content-Length: 305
Host: 127.0.0.1
Content-Type: application/x-www-form-urlencoded
Connection: close

params=%7B%22mts%22%3A+%5B%7B%22account_type%22%3A+5%2C+%22account
%22%3A+%222322231%22%2C+%22bitrate%22%3A+2048%2C+%22protocol%22%3A
+0%7D%2C+%7B%22account_type%22%3A+5%2C+%22account%22%3A+%222322232
%22%2C+%22bitrate%22%3A+2048%2C+%22protocol%22%3A+0%7D%5D%7D&
account_token=6567e24b425db665a3044db69f0c6fe4

3.4 答复

    任何操作都有success标识成功失败
    失败操作统一用error_code标识错误码
    数据形式为json，字符编码utf-8

Content-Type: application/json;charset=utf-8;

范例（添加终端回复为例）

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 27 Jun 2016 07:52:28 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 31
Connection: close

{"success": 1, "error_code": 0}

4 系统状态码

https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html