跳到主要内容

API概述

整体风格#

URI风格#

URI采用RESTful 的设计风格:

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

其中当前版本versionv1

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,并导入到科达视频会议系统中。 通过AppKeyAppSecret向平台注册获取account_token

请求格式:

POST /api/v1/system/token HTTP/1.1Content-Type: application/x-www-form-urlencodedUser-Agent: PostmanRuntime/7.28.1Accept: */*Cache-Control: no-cachePostman-Token: 2a5610ba-949b-4bfa-a5c6-4c9a636f792eHost: 10.67.16.26Accept-Encoding: gzip, deflate, brConnection: keep-aliveContent-Length: 44
oauth_consumer_secret=ierasdasd12d&oauth_consumer_key=assfgsd

回复格式:

HTTP/1.1 200 OKServer: openrestyDate: Mon, 05 Jul 2021 02:24:33 GMTContent-Type: application/jsonTransfer-Encoding: chunkedConnection: keep-alive
{"account_token":"4407933cc3f417cd3c7a01a7cb20e1a6","success":1}

用户登陆#

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

请求格式:

POST /api/v1/system/login HTTP/1.1Content-Type: application/x-www-form-urlencodedUser-Agent: PostmanRuntime/7.28.1Accept: */*Cache-Control: no-cachePostman-Token: 3edfa47d-deb9-4293-8116-c96ef1956817Host: 10.67.16.26Accept-Encoding: gzip, deflate, brConnection: keep-aliveContent-Length: 82
account_token=4407933cc3f417cd3c7a01a7cb20e1a6&password=888888&username=test

回复格式:

HTTP/1.1 200 OKServer: openrestyDate: Mon, 05 Jul 2021 02:24:35 GMTContent-Type: application/jsonTransfer-Encoding: chunkedConnection: keep-aliveSet-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_tokencookie的有效期,若长时间无操作,开发者需要自行调用接口刷新tokenCookie的有效期。

获取类请求#

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

GET /api/v1/krtc/rooms?account_token=69c08f7f1daf84257b0004f219b7b7f8 HTTP/1.1API-Level: 3User-Agent: PostmanRuntime/7.28.1Accept: */*Cache-Control: no-cachePostman-Token: 8220cf8e-a77e-4d74-9d6a-d1ab3dd66bc3Host: 10.67.16.26Accept-Encoding: gzip, deflate, brConnection: keep-aliveCookie: 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.1Content-Type: application/jsonUser-Agent: PostmanRuntime/7.28.1Accept: */*Cache-Control: no-cachePostman-Token: 0c1e2201-07da-4869-a2e7-f167b2c59d65Host: 10.67.16.26Accept-Encoding: gzip, deflate, brConnection: keep-aliveContent-Length: 146Cookie: SSO_COOKIE_KEY=10c2fc66-4ba3-4be5-9acd-b4477a59f167.mooooooo-oooo-oooo-oooo-defaultmachiAPI-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 OKServer: openrestyDate: Mon, 05 Jul 2021 02:08:45 GMTContent-Type: application/json; charset=UTF-8Content-Length: 102Connection: keep-aliveVary: Accept-Encoding
{"room_id": "8887857", "meeting_id": "14009", "description": "\u64cd\u4f5c\u6210\u529f", "success": 1}

失败回复:

HTTP/1.1 200 OKServer: openrestyDate: Mon, 05 Jul 2021 02:08:45 GMTContent-Type: application/json; charset=UTF-8Content-Length: 102Connection: keep-aliveVary: 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.1API-Level: 3User-Agent: PostmanRuntime/7.28.1Accept: */*Cache-Control: no-cachePostman-Token: a4783a8d-cbd1-469d-8341-cf4ed5ad2496Host: 10.67.16.26Accept-Encoding: gzip, deflate, brConnection: keep-aliveCookie: SSO_COOKIE_KEY=b9115245-1578-4929-82cd-4a517141e603.mooooooo-oooo-oooo-oooo-defaultmachi

成功回复:

HTTP/1.1 200 OKServer: openrestyDate: Mon, 05 Jul 2021 02:37:03 GMTContent-Type: application/json; charset=UTF-8Content-Length: 57Connection: keep-aliveVary: 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.1API-Level: 3User-Agent: PostmanRuntime/7.28.1Accept: */*Cache-Control: no-cachePostman-Token: 070b8025-fe3d-4505-a7f0-3d7c1c8b330cHost: 10.67.16.26Accept-Encoding: gzip, deflate, brConnection: keep-aliveCookie: SSO_COOKIE_KEY=10c2fc66-4ba3-4be5-9acd-b4477a59f167.mooooooo-oooo-oooo-oooo-defaultmachiContent-Length: 0

兼容性策略#

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

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

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

版本说明#

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

API-Level:1V6.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.1User-Agent: PostmanRuntime/7.28.1Accept: */*Cache-Control: no-cachePostman-Token: 373e3d66-600e-4226-9feb-05645a639fbeHost: 10.67.16.26Accept-Encoding: gzip, deflate, brConnection: keep-alive

成功回复:

HTTP/1.1 200 OKServer: openrestyDate: Mon, 05 Jul 2021 02:46:10 GMTContent-Type: application/json; charset=UTF-8Content-Length: 63Connection: keep-aliveEtag: "466e3246678bac123faef1ff6711bd22b3ddfdc0"Vary: Accept-Encoding
{"success": 1, "version": "6.1.0.4.0.20200610", "api_level": 3}

向后兼容#

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

  1. API参数字段变化
  2. API路径变化
  3. API参数值含义变化
  4. 返回数据中字段的增删

私有云环境下,有可能存在视频会议平台升级了版本,但第三方基于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.1API-Level: 3User-Agent: PostmanRuntime/7.28.1Accept: */*Cache-Control: no-cachePostman-Token: 8220cf8e-a77e-4d74-9d6a-d1ab3dd66bc3Host: 10.67.16.26Accept-Encoding: gzip, deflate, brConnection: keep-aliveCookie: SSO_COOKIE_KEY=10c2fc66-4ba3-4be5-9acd-b4477a59f167.mooooooo-oooo-oooo-oooo-defaultmachi