HTTP API设计指南

URI规则

1. 资源名为复数形式。
   eg./orders :订单集合。
   eg./users :用户集合。
   eg./users/123 :用户123。
2. 全小写英文单词。
   eg./orders/123/pay :为编号为123的订单付款。
3. 用URL路径标识资源层级，但是层级不要过多。
   eg./users/123/orders :用户123的所有订单集合。
   eg./users/123/orders/123 :应为/orders/123。
4. 用-分割多单词的路径名。
   eg./app-setting :app的设置。
   eg./activity-orders :活动订单。
5. 用_分割多单词的‘?’查询部分参数名。
   eg./activities?activity_type=1 :活动类型为1的活动集合。

‘/’路径部分

仅一下3部分内容会出现在路径中:

1. 资源名。
   eg./orders:订单集合
2. 资源主键的值。
   eg./orders/123':编号为123的订单。
3. 资源的操作行为（仅限get、post、put、delete无法涵盖的操作行为）。
   eg./orders/123/cancel:取消编号为123的订单。
   eg./activities/123/onsale:上架编号为123的活动。

‘?’查询参数部分

以下两部分内容会出现在查询部分。

1. 资源的非主键属性作为查询条件时。
   eg./orders?status=paid:付款成功的订单集合。
2. 排序、分页的参数（通用部分，参数名以及格式作统一处理）。
   2.1 分页参数:page表示第几页，最小值是1，默认值是1；page_size表示分页大小，默认值是10。
   eg./orders?page=2&page_size=12:取第二页，每页12条数据。
   2.2 排序参数：order_by包含排序字段和排序方式两部分，用“,”分割;可同时指定多个排序字段，用“;”分割。
   eg.order_by=create_time,asc;like_count,desc:先按照创建时间升序排列，再按照收藏数量降序排序。

Asp.Net Web Api路由实施规范

路由实施规范的命名规则受以上的URL规则所约束。

1. RoutePrefix:所有公开的ApiController必须添加RoutePrefix(“”)特性。
   2.Route:所有公开的Action必须添加Route(“”)。
   3.所有公开的Action必须至少添加一个特性（HttpGet、HttpPost、HttpPut、HttpDelete）。

HTTP Status Code

对资源的操作的成功或者失败，尽量的使用通用的状态码表示。

Status Code	HTTP Method
200 OK	GET,POST,PUT	获取数据成功
201 Created	POST	创建资源成功
204 Not Content	DELETE	没有返回结果
400 Bad Request	*	客户端错误的请求,同时携带错误响应消息
401 Unauthorized	*	未授权
403 Forbidden	*	禁止访问
404 Not Found	*	未找到
500 Internal Server Error	*	内部服务器错误

HTTP Header

Header	用途	示例值
Authorization	权限验证	token xxx
Accept	请求方期望接受的数据格式	application/json
Content-Type	HTTP消息实体的数据格式	application/json