跳到主要内容

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.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_tokencookie的有效期,若长时间无操作,开发者需要自行调用接口刷新tokenCookie的有效期。

获取类请求

参数平铺跟在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接口还是可能存在不兼容的问题,包括但不限于:

  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.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