API概述

概述

摩云视讯平台API，主要为希望对视频会议进行二次开发的开发者提供一套完整的接口。

整体风格

URI风格

URI采用RESTful 的设计风格：

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

其中当前版本version为v1

app分类为：

模块	app
统一登录	system
会议管理	mc
会议控制	vc
账号管理	amc
录播系统	vrs
统一出席	upu

时间格式

采用ISO8601:2000标准

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

请求方法

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

使用说明

APP鉴权

摩云视讯平台API采用统一登录方式对软件权限及用户账户进行验证，使用者仅需登录一次，便可调用各子系统的API。使用者需先申请API License，并导入到摩云视频会议系统中。通过AppKey和AppSecret向平台注册获取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
API-Level: 1

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
API-Level: 1

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"}

平台使用Cookie来保存用户的登录信息。调用后续接口时，需要在每次请求的时候携带account_token及用户Cookie。每次请求会刷新account_token和cookie的有效期，若长时间无操作，开发者需要自行调用接口刷新token和Cookie的有效期。

获取类请求

参数平铺跟在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

修改类请求（POST/PUT）

参数以表单形式x-www-form-urlencoded提交，字符编码为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
API-Level: 1

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

回复格式

数据形式为json，字符编码utf-8

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

任何操作都有success标识请求成功失败失败是会有error_code字段标识错误码

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

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}

兼容性策略

由于我司会议平台主要应用场景为私有云部署，不同的客户或同一客户的不同地区可能使用不同的版本，且较难升级为同一版本。

因此调用方可能需要考虑兼容不同版本的平台，包括向前兼容和向后兼容。

为了方便区分平台的版本，采用API-Level字段来描述API版本。

版本说明

API说明文档中每个App模块的API-Level与文档对应的平台版本号，可以在右上角查询到：

API-Level：1;
V6.0.0.3.0.20190826;

每个API接口，也会标注其所需的最低API-Level，若环境的API-Level低于接口描述终端最低需求版本，则该环境不支持该API接口。

如下例代表该接口最低支持的API-Level为3，若平台的API-Level版本为2，则说明平台不支持该接口。

名称          获取个人模板列表
URI           /api/v1/mc/personal_templates
方法          GET
说明          获取个人模板列表
最低支持版本  3
...

查询API-Level

为了便于调用方查询当前环境的API版本，每个模块都提供了API-Level查询接口：

格式为：

GET /api/{app}/version;

如：

GET /api/system/version;
GET /api/vc/version;
GET /api/mc/version;
...

向后兼容

由于平台功能的演进，API接口及参数可能会不断变化，一般情况下，我们会尽量避免做出影响兼容性的改动，但极少数情况下，API接口还是可能存在不兼容的问题，包括但不限于：

API参数字段变化
API路径变化
API参数值含义变化
返回数据中字段的增删

私有云环境下，有可能存在视频会议平台升级了版本，但第三方基于API开发的业务没有计划升级的情况。

为了能最大限度保证这种情况下的兼容性，减少二次开发的工作量，建议调用方在调用API时，告知平台其所用的API-Level。

当调用方携带的API-Level小于平台的API-Level时，平台会进行兼容性处理，按照给定的API-Level版本的格式解析参数、返回数据。

当调用方携带的API-Level大于平台版本时，平台则会按其所支持的最高API-Level版本的格式解析参数、返回数据

API-Level需要携带在HTTP头中，如下例：

GET /api/v1/mc/personal_templates?account_token=6567e24b425db665a3044db69f0c6fe4 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
API-Level: 1

调试模式

由于部分接口参数众多，当调用方调用出错时，可以使用调试模式来校验填写的参数是否合法。

使用方法为在请求的URI中携带参数debug=1，如：

POST /api/v1/vc/confs/1118986/mts?debug=1 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++%22protocol%22%3a+0%7d%5d%7d&account_token=6567e24b425db665
a3044db69f0c6fe4

开启调试模式后，平台仅会对接口进行参数校验，并返回校验结果，并不会实际执行。

平台会在返回数据的debug_list字段中给出错误提示，数据格式如下:

"debuglist":{
    "第一层key":{
        "第二层key":"错误说明"
    },
    "第一层key":[
        {"第二层key":"错误说明"}
    ]
}

下述返回表示参数mts列表中缺少必填参数bitrate

{
    "success":1,
    "dubug_list":{
        "mts":[
            {"bitrate":"下参中缺少该必填参数"}
        ]
    }
}

API概述

概述​

整体风格​

URI风格​

时间格式​

请求方法​

使用说明​

APP鉴权​

用户登录​

获取类请求​

修改类请求（POST/PUT）​

回复格式​

兼容性策略​

版本说明​

查询API-Level​

向后兼容​

调试模式​

概述