关于Restful API与状态码的设计

一、API

1. 传输协议

采用HTTP JSON通讯协议

2. API版本控制

将API得版本号放入URL，http://api.example.com/v{n}/
v{n} n代表版本号，使用整形得版本号，例如v1, v2

3. 请求方法

对于资源的具体操作类型，由HTTP动词表示。

• GET（SELECT）：从服务器取出资源（一项或多项）。
• POST（CREATE）：在服务器新建一个资源。
• PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
• PATCH（UPDATE）：在服务器更新资源（客户端提供改变后的部分资源）
• DELETE（DELETE）：从服务器删除资源。

4. 路径规则

API中的名词也应该使用复数, http://api.example.com/v1/orders

• GET/orders/{ID}：获取某个指定订单的信息
• POST/orders/list：列出订单
• POST/orders：新建一个订单
• PUT/orders/{ID}：更新某个指定订单的信息
• PATCH/orders/status/{ID}：更新某个指定订单的状态
• DELETE/products/{ID}：删除某个订单

1. 列出资源一般使用GET方法，然后在URL中携带参数，这里使用POST方法的考虑是POST方法使body携带参数更加好表达一下条件参数，另外使用URL携带有长度限制(某些场景可能需要携带较多的参数)，不必强制符合restful规范，应该结合实际场景处理。
2. 对与类似token这样的参数，可以将参数放置Header进行携带

5. 请求报文示例

1. 列出订单
   POST /orders/list

请求体

{
   
    "count": 10, 
    "page"