文档介绍：接口定义规范
研发部
2018/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 rs?filter="name::todd|city::denver|title::grand poobah”
排序字段也应该合并到一个参数里,使用-代表倒序
GET rs?sort=last_name|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-ded
响应内容格式为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中返回对象内容。
204 No content
处理成功,但没返