REST API v1

概要

此文档描述了Vnnox系统的REST API(v1)，如果您在使用中有任何问题请及时联系

• 版本
• 请求简述
• 参数说明
• 服务地址
• 错误调试
• HTTP方法
• 认证
• 分页
• 次数限制
• 用户代理

版本

默认情况下当客户端访问https://cn.vnnox.com时，系统将使用V1 版REST API提供服务，我们建议您在http请求的heaer中的`Accept`字段加上服务版本号。格式如下：

Accept:application/nova.vnnox.v1+json

注：为了不影响第三方功能对接，当前v1版本的REST API接口及接口中的数据会以增量方式更新。

请求简述

所有请求均通过HTTPS协议，API请求链接为https://cn.vnnox.com，所有数据的请求及相应均通过json格式。

Response数据结构

{
    "http_code": 200,            //http状态码(重要：请使用http协议本身的状态码做异常捕获，response data中http_code字段后期会取消掉)
    "data": {...some data...},   //数据部分
    "status": [10000001]         //业务相关状态码
}

请求列表

通过GET请求获取资源信息时，如果未指定资源唯一ID，则请求的为资源的列表，返回的数据list中包含了符合查询规则的集合list

{
    "http_code": 200,
    "data": {
        "userList": [
            {
                "uid": "2",
                "oid": "6",
                "wid": "311",
                "enable": "1",
                "org_reg": "0",
                "uName": "user1",
                "user_conf": {...},
                "user_statistic": {... },
                "workgroup": {... },
                "role": [...]
            },
            {
                "uid": "20",
                "oid": "6",
                "wid": "3113",
                "enable": "1",
                "org_reg": "0",
                "uName": "user2",
                "user_conf": {...},
                "user_statistic": {...},
                "workgroup": {... },
                "role": [... ]
            }
        ],
        "count": "3"
    },
    "status": [
        10000001
    ]
}

请求详情

如果在资源请求中指定唯一ID,则请求的为单个资源，返回的数据只包含当前资源

{
    "http_code": 200,
    "data": {
        "uid": "2567",
        "oid": "67",
        "wid": "3114",
        "enable": "1",
        "org_reg": "0",
        "uName": "lileilei_3",
        "user_conf": {...},
        "role": [...],
        "workgroup": [...],
        "systemMediaApprove": "0"
    },
    "status": [
        10405001
    ]
}

参数说明

很多API方法使用可选参数，如`GET`请求中会存在`资源名称`和`查询参数`:

{host}/Rest/Medias?offset=0&limit=10&search=&sort=last_amendment_time&sortType=desc

在上述例子中，‘Rest’、‘Medias’代表了资源名称，`offset`、`limit`、`search`、`sort`、`sortType`代表了查询参数。

在`POST`、`PUT`请求中，无法包含在url中的参数需要格式化为JSON 并使用 Content-Type : 'application/json'方式请求接口

服务地址

Vnnox REST API均使用`host` + `resource` + `parameters` 的请求方式与服务器交互，`host`指服务器地址：https://cn.vnnox.com/，`resource`指资源及资源路径，一般为`Rest/{资源名}/`， `parameters`为资源标识或者查询参数：

GET {host}/Rest/Medias?offset=0&limit=10&search=&sort=last_amendment_time&sortType=desc
GET {host}/Rest/Medias/{media_id}
PUT {host}/Rest/Player/{player_id}
DELETE {host}/Rest/User/{user_id}
POST {host}/Rest/Worker

如上面的例子，本文档所有涉及{host}均指https://cn.vnnox.com/，建议第三方开发者将{host}信息作为可配置项

错误调试

在REST API请求时会有3类错误：

1、服务级错误：网络或运营商导致的服务级别错误。（建议第三方应用中捕获http不等于2xx的状态码，如404、502等）

HTTP/1.1 502 Bad Gateway

2、系统级错误：REST API 请求中传入了非法参数或者数据格式错误。（建议第三方在应用中捕获 json.status[0] = 1）

HTTP/1.1 200 ok

{
    "data": "系统级错误，请联系VNNOX管理员，谢谢！",
    "status": [1]
}

3、业务级错误：REST API因业务限制返回的状态码/错误码（json.status）。（建议第三方应用根据状态码说明处理API结果）

HTTP/1.1 200 ok

{
    "http_code": 200,
    "data": {
        "roleName": ""
    },
    "status": [50101201]
}

HTTP方法

Vnnox REST API 目前支持4中HTTP方法：

认证

Vnnox REST API使用Oauth2.0认证，请使用认证接口获取token(加入到 HTTP-header中)

token:5c1354529946bc49360641f7f321611698deb371

分页

当请求资源列表时，需要指定分页参数：

GET {host}/Rest/Player?offset=0&limit=10&search=&sort=name&sortType=asc

次数限制

使用Oauth2.0认证的REST API访问，同一个用户获取的token访问频次建议1小时内不要超过3000次。

用户代理

所有的API请求一般都会包含User-Agent header，例如浏览器会默认设定为`Mozilla/5.0`等，如果第三方应用对接VNNOX REST API，请参数如下设置：

User-Agent: Vnnox-User-App

如果应用的HTTP请求中没有此参数设定，系统无法验证当前用户的Request请求来源，可能会影响到数据的访问。