文档介绍：接口定义规范
研发部
/01
1． URI命名规范 3
2． 使用HTTP方法表示动作行为 4
3． 使用HTTP内容协商处理资源表示内容 4
4． 使用HTTP响应状态码标识处理结果状态 5
5． 使用 HAL(Hypertext Application Language)作为响应数据格式 6
6． 各HTTP方法成功处理后返回数据 9
7． 不要对返回结果进行封装 9
8． 支持资源字段裁剪，降低响应中返回字段数量 10
9． 使用 OAuth2 来确保 API 安全性 10
10． 确保GET，PUT，DELETE 请求是幂等 10
11． API版本 10
微服务接口设计采取Restful风格接口规范，下面是基于Restful风格要求制订接口设计规范。
URI命名规范
不用大写；
用中杠-不用下杠_；
参数列表要encode；
使用名词作为资源名称 (比如，不要在网址中使用动词)；
使用资源集合概念；
每种资源有两类URI（接口）：
资源集合（比如，/orders）；
集合中单个资源（比如，/orders/{orderId}）。
使用复数形式 (使用 ‘orders’ 而不是 ‘order’)；
资源名称和 ID 组合能够作为一个网址节点；
比如，/orders/{orderId}/items/{itemId}；
尽可能让网址越短越好，单个网址最好不超出三个节点。
能够使用查询参数替换路径中节点组合
对Composite资源访问
服务器端组合实体必需在uri中经过父实体id导航访问。
GET /orders/12/items
使用有意义资源描述；
“严禁单纯使用 ID!” 响应信息中不应该存在单纯 ID，应使用链接 或是引用对象；
设计资源表述信息，而不是简简单单做数据库表映射；
合并表述信息，不要经过两个 ID 直接表示两个表关系；
资源集合应支持过滤，排序和分页；
过滤、排序、分页应出现在参数列表中而不是Path中。
比如：GET /currencies?page=1&size=10
过滤条件应该合并到一个参数里：
GET "name::todd|city::denver|title::grand poobah”
排序字段也应该合并到一个参数里,使用-代表倒序
GET |first_name|-hire_date
常常使用、复杂查询标签化，降低维护成本。
如：
GET /trades?status=closed&sort=created desc
快捷方法：
GET /trades/recently-closed
使用HTTP方法表示动作行为
POST - 创建资源，非幂等性操作；
PUT - 更新资源；
PATCH - 部分更新资源；
GET - 获取单个资源或资源集合；
DELETE - 删除单个资源或资源集合；
标准上URI中不应该出现动词，当出现复杂操作超出上述HTTP方法描述行为时，能够考虑经过URL参数来指定动作。
如 PUT /books/1?action=like 标注ID为1图书为喜爱图书
使用其它动作时，HTTP方法仍然依据实际操作属于那种类型设定，比如属于资源更新操作，那么就使用PUT方法。
使用HTTP内容协商处理资源表示内容
经过请求头/响应头中Content-Type判定请求提中数据类型，然后依据数
据类型做出对应处理。
请求Body内容格式采取JSON格式，其格式经过HTTP Header Content-Type:application/json表示。
或From表单格式，其格式经过HTTP Header：
Content-Type: application/x-www-form-urlencoded
响应内容格式为JSON，响应头Content-Type:application/json
或HAL+JSON，响应头为Content-Type:application/hal+json
或XML格式，响应头为Content-Type:text/xml
使用HTTP响应状态码标识处理结果状态
不要发生了错误但给2xx响应，用户端可能会缓存成功http请求；
正确设置http状态码，不要自定义；
下面是常见状态码及其意义：
响应码
说明
200 OK
请求处理正常，通常见于GET操作时内容正常返回
201 Created
Post或PUT操作时对象被正常创建，通常在Body中返回对