基本接口说明

Ox的基本接口遵循 Zero 的接口规范，本文用于说明整个平台统一的接口基础规范，为公开性文档。

1. 统一术语

术语	默认值	说明
HOST	无	部署服务器的IP地址或域名
PORT	6083	部署服务器的默认调用端口
ADDR	无	接口的地址名称，请求相对路径
PATH	无	接口除开 HOST 和 PORT 的全路径

2. 基本设计原则

• 非安全类型的API语法格式：http://<HOST>:<PORT>/<ADDR>——不需要任何用户名和密码可访问的接口。
• 安全类型的平台资源API语法格式：http://<HOST>:<PORT>/api/<ADDR>——需要通过了 401 和 403 的认证授权后可访问的平台资源语法格式。如果修改，必须重启容器。
• 安全类型的动态资源API语法格式：http://<HOST>:<PORT>/api/ox/<ADDR>——需要通过了 401 和 403 的认证授权后可访问的动态接口语法格式，动态接口可直接在平台中添加、编辑、删除，并且在运行过程中配置。修改后可不用重启容器。
• 【重要】所有的HTTP请求中必须带上服务端偏好信息，在HTTP头部加上：Content-Type: application/json请求头。
• 多租户原则：在平台中如果运行了多个租户信息，则需要在资源请求中加上：X-Sigma自定义请求头，用于标识租户。
• 多应用原则：在平台中每个租户如果拥有多个应用容器，则需要在资源请求中加上：X-AppId自定义请求头，用于标识租户下的应用信息。
• 应用安全原则：在平台中访问每个应用资源时，根据资源等级对特殊资源的访问必须加上：X-AppKey自定义请求头。
• 多语言原则：多语言环境中，资源请求需要加上：X-Lang自定义请求头。

3. 统一请求说明

3.1. HTTP头

头名称	必须/满足条件必须	值
Content-Type	Required	application/json
X-Sigma	Conditional	多租户必须
X-AppId	Conditional	多应用必须
X-AppKey	Conditional	应用敏感数据必须
X-Lang	Conditional	多语言必须

3.2. 统一响应格式

Ox平台的统一响应格式参考Zero的RESTful设计规范，基本响应格式如下：

{
    "data": "（可支持多种格式）",
    "metadata": "（保留，终端抽象层）",
    "extension": "（保留，终端扩展层）",
    "resolver": "（保留，终端适配层）"
}

目前的版本中，大部分请求不包含 metadata，extension，resolver 节点。

参数	说明
data	data为异构数据格式，常见的数据类型包含三大类：Json对象、Json数组、基本数据格式。
metadata	保留
extension	保留
resolver	保留

3.3. 统一异常格式

异常发生时，HTTP状态代码不会使用 200 或 201 的代码，不同状态代码会标识容器内部不同的异常信息，该代码主要包含：4xx 和 5xx，遵循标准HTTP应用层协议规范。

1. 4xx：客户端异常
2. 5xx：服务端异常

Ox平台的统一异常格式参考 Zero 的RESTful设计规范，基本格式如下：

{
    "code": -1,
    "message": "（系统异常）",
    "info": "（业务异常）"
}

参数	说明
code	格式为负数5位、或者负数6位，5位是原生Zero框架内部定义，6位是扩展定义，内部错误代码，可直接在错误代码表中查询错误来源。
message	系统异常信息，一般为 Java Stack 信息，可帮助开发人员调试接口。
info	（可选）业务异常信息，一般提供给终端消费，不同的终端需要的异常信息有所不同，如：“用户名密码错。”，“账号不存在。”。