关于REST
前后端接口按照粗浅的REST规则制定，其主要表现为：
使用GET、POST、PUT、DELETE共4个HTTP Method，而非简单的GET和POST两者。
响应使用HTTP状态码来标志请求的执行结果，而非以往的success字段。
URL符合业界普遍接受的REST规则，减少在URL中标识操作类型的情况，如使用POST /users代替POST /users/save。
出于技术的限制，对于一些特殊的场景，接口会在REST设计的基础之上进行一些妥协，具体参考各接口规范说明。
在REST接口规范中，URL符合以下约束：
实体名称均以复数形式表示，如GET /users或POST /users/status。
URL最后 不得 添加斜杠/符号。
对于GET请求，数据在URL后通过标准的query格式提供，如GET /users?status=1,2&keyword=hello。
对于各系统，可以在URL前统一添加固定的前缀，如GET /api/{entities}/{id}，前缀应尽量固定。可以根据请求的类型（如是否需要用户登录授权等）使用不同的前缀。规范推荐按以下规则使用前缀：
如果是需要登录授权的接口，以/api/js为前缀。
其它接口，通常没有权限控制，以/api/tool为前缀。
关于数据类型
请求可以使用以下两类数据类型，由具体的项目及接口根据实际情况决定：
表单编码格式。此格式为简单的a=b&c=d这一形式，使用此请求格式时，请求的Content-Type头的值必须为application/x-www-form-urlencoded。
JSON格式。此格式为一个完整的符合JSON格式的串，使用此请求格式时，请求的Content-Type头的值必须为application/json。
响应可以使用以下几类数据类型：
JSON格式。多数接口应当使用JSON格式的响应，此时响应的Content-Type头的值必须为application/json。
HTML格式。部分接口，如文件上传，由于技术的限制必须使用<iframe>元素完成，返回的响应为一个HTML片段，此时响应的Content-Type头的值必须为text/html，且响应状态码必须为200，具体可参考下文的文件上传相关接口规范。
JSONP格式。当跨系统调用API时，会需要使用JSONP接口，此时响应的Content-Type头的值必须为application/x-javascript，使用请求的URL中的callback字段的值为函数名返回相应的JSONP片段。
关于编码
所有请求和响应均 必须 使用utf-8为编码。此标准体现在请求和响应的Content-Type头的值后必须配有;charset=utf-8字样。
对于前端使用JSONP的场景，则应当为
用户列表
用于获取用户列表，带分页功能
接口：
GET /users
请求参数：
| 名称 | 类型 | 定义 | 必需 | 默认值 | 说明
| keyword | string | 查询关键词 | | “” | 作用于name和id字段
| page | number | 页码 | | 1 |
| role | number | 角色 | | 全部 | 参考角色枚举说明
| orderBy | string | 排序字段名称 | | “id” | 可以使用”id”或”name”
| order | string | 排序方式 | | “asc” | 可以为”asc”或”desc”
响应：
成功：200
响应格式：JSON
{
totalCount: {number}, // 总数
results: [
{
"id": {number},
"name": {string},
"role": [{number}, ...], // 角色，多个角色用数组表示
"birthday": {string}, // 生日使用YYYYMMDD格式
},
...
]
}
缓存配置：使用ETag进行缓存。
参数不合法：409
参考标准409响应
在文档中，对于一些整个项目统一的内容，如页码默认值为1之类，可以省略说明，在单独的总体设计文档中标注即可。