API概述

整体风格

URI风格

URI采用RESTful 的设计风格：

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

其中当前版本version为v1

app分类为：

模块	app
统一登录	system
房间管理	krtc

时间格式

采用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
Content-Type: application/x-www-form-urlencoded
User-Agent: PostmanRuntime/7.28.1
Accept: */*
Cache-Control: no-cache
Postman-Token: 2a5610ba-949b-4bfa-a5c6-4c9a636f792e
Host: 10.67.16.26
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 44

oauth_consumer_secret=ierasdasd12d&oauth_consumer_key=assfgsd

回复格式：

HTTP/1.1 200 OK
Server: openresty
Date: Mon, 05 Jul 2021 02:24:33 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive

{"account_token":"4407933cc3f417cd3c7a01a7cb20e1a6","success":1}

用户登录

使用用户的帐号、密码登录和上一步获取的account_token进行登录

请求格式：

POST /api/v1/system/login HTTP/1.1
Content-Type: application/x-www-form-urlencoded
User-Agent: PostmanRuntime/7.28.1
Accept: */*
Cache-Control: no-cache
Postman-Token: 3edfa47d-deb9-4293-8116-c96ef1956817
Host: 10.67.16.26
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 82

account_token=4407933cc3f417cd3c7a01a7cb20e1a6&password=888888&username=test

回复格式：

HTTP/1.1 200 OK
Server: openresty
Date: Mon, 05 Jul 2021 02:24:35 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: SSO_COOKIE_KEY=b9115245-1578-4929-82cd-4a517141e603.mooooooo-oooo-oooo-oooo-defaultmachi;path=/;HttpOnly=true

{"userdomainname":"autotest","success":1,"usermoid":"09572f84-dbb6-446c-8786-958d4088f334","userdomainmoid":"6f8o9frpjt5ucau6i5mwggyw","username":"autotest"}

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

获取类请求

参数平铺跟在URI后面，以&区分多参数,account_token也是携带在url中，cookie携带在header中范例（获取房间列表为例）

GET /api/v1/krtc/rooms?account_token=69c08f7f1daf84257b0004f219b7b7f8 HTTP/1.1
API-Level: 3
User-Agent: PostmanRuntime/7.28.1
Accept: */*
Cache-Control: no-cache
Postman-Token: 8220cf8e-a77e-4d74-9d6a-d1ab3dd66bc3
Host: 10.67.16.26
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Cookie: SSO_COOKIE_KEY=10c2fc66-4ba3-4be5-9acd-b4477a59f167.mooooooo-oooo-oooo-oooo-defaultmachi

修改类请求（POST）

参数以json格式放到body中

Content-Type: application/json

范例（以创建房间为例）：

POST /api/v1/krtc/rooms?account_token=69c08f7f1daf84257b0004f219b7b7f8 HTTP/1.1
Content-Type: application/json
User-Agent: PostmanRuntime/7.28.1
Accept: */*
Cache-Control: no-cache
Postman-Token: 0c1e2201-07da-4869-a2e7-f167b2c59d65
Host: 10.67.16.26
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 146
Cookie: SSO_COOKIE_KEY=10c2fc66-4ba3-4be5-9acd-b4477a59f167.mooooooo-oooo-oooo-oooo-defaultmachi
API-Level: 3

{
     "room_name": "SFUROOM",
     "max_join_mt": 192,
     "room_type": 2,
     "resolution": 12,
     "bitrate": 2048,
     "format": 5,
     "frame": 60
}

回复格式

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

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

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

范例（以创建房间为例）:

成功回复：

HTTP/1.1 200 OK
Server: openresty
Date: Mon, 05 Jul 2021 02:08:45 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 102
Connection: keep-alive
Vary: Accept-Encoding

{"room_id": "8887857", "meeting_id": "14009", "description": "\u64cd\u4f5c\u6210\u529f", "success": 1}

失败回复：

HTTP/1.1 200 OK
Server: openresty
Date: Mon, 05 Jul 2021 02:08:45 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 102
Connection: keep-alive
Vary: Accept-Encoding

{"success": 0, "error_code": 27506,"description": "当前没有空闲会议资源，创建会议失败(27506)"}

删除类请求（DELETE）

参数平铺跟在URI后面，以&区分多参数,account_token也是携带在url中，cookie携带在header中

范例（以删除房间为例）:

DELETE /api/v1/krtc/rooms/8887865?account_token=f392fd92a3d2872692b0b7fb68e9b814 HTTP/1.1
API-Level: 3
User-Agent: PostmanRuntime/7.28.1
Accept: */*
Cache-Control: no-cache
Postman-Token: a4783a8d-cbd1-469d-8341-cf4ed5ad2496
Host: 10.67.16.26
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Cookie: SSO_COOKIE_KEY=b9115245-1578-4929-82cd-4a517141e603.mooooooo-oooo-oooo-oooo-defaultmachi

成功回复：

HTTP/1.1 200 OK
Server: openresty
Date: Mon, 05 Jul 2021 02:37:03 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 57
Connection: keep-alive
Vary: Accept-Encoding

{"success": 1, "description": "\u64cd\u4f5c\u6210\u529f"}

如果客户端不支持DELETE请求，可以在参数中使用_method=DELETE的方式发送请求，范例如下：

POST /api/v1/krtc/rooms/8887857?account_token=69c08f7f1daf84257b0004f219b7b7f8&_method=DELETE HTTP/1.1
API-Level: 3
User-Agent: PostmanRuntime/7.28.1
Accept: */*
Cache-Control: no-cache
Postman-Token: 070b8025-fe3d-4505-a7f0-3d7c1c8b330c
Host: 10.67.16.26
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Cookie: SSO_COOKIE_KEY=10c2fc66-4ba3-4be5-9acd-b4477a59f167.mooooooo-oooo-oooo-oooo-defaultmachi
Content-Length: 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查询接口，不需要携带account_token和cookie即可查询：

格式为：

GET /api/{app}/version

范例（以KRTC版本为例）:

GET /api/krtc/version HTTP/1.1
User-Agent: PostmanRuntime/7.28.1
Accept: */*
Cache-Control: no-cache
Postman-Token: 373e3d66-600e-4226-9feb-05645a639fbe
Host: 10.67.16.26
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

成功回复：

HTTP/1.1 200 OK
Server: openresty
Date: Mon, 05 Jul 2021 02:46:10 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 63
Connection: keep-alive
Etag: "466e3246678bac123faef1ff6711bd22b3ddfdc0"
Vary: Accept-Encoding

{"success": 1, "version": "6.1.0.4.0.20200610", "api_level": 3}

向后兼容

由于平台功能的演进，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/krtc/rooms?account_token=69c08f7f1daf84257b0004f219b7b7f8 HTTP/1.1
API-Level: 3
User-Agent: PostmanRuntime/7.28.1
Accept: */*
Cache-Control: no-cache
Postman-Token: 8220cf8e-a77e-4d74-9d6a-d1ab3dd66bc3
Host: 10.67.16.26
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Cookie: SSO_COOKIE_KEY=10c2fc66-4ba3-4be5-9acd-b4477a59f167.mooooooo-oooo-oooo-oooo-defaultmachi

API概述

整体风格​

URI风格​

时间格式​

请求方法​

使用说明​

APP鉴权​

用户登录​

获取类请求​

修改类请求（POST）​

回复格式​

删除类请求（DELETE）​

兼容性策略​

版本说明​

查询API-Level​

向后兼容​

整体风格

URI风格

时间格式

请求方法

使用说明

APP鉴权

用户登录

获取类请求

修改类请求（POST）

回复格式

删除类请求（DELETE）

兼容性策略

版本说明

查询API-Level

向后兼容