RESTful Api设计

#拆分资源

”资源“应该是个名词
内部数据模型和资源对应起来
不需要把它们一对一的都暴露出来。隐藏内部资源，暴露必需的外部资源。
一旦定义好了要暴露的资源，你可以定义资源上允许的操作

:::text
GET /blog # 获取blog列表
GET /blog/12 # 查看某个具体的blog
POST /blog # 新建一个blog
PUT /blog/12 # 更新blog 12.
DELETE /blog/12 #删除blog 12

REST的好处在于可以充分利用http的强大实现对资源的CURD功能。而这里你只需要一个endpoint：/blog,再没有其他什么命名规则和url规则了

#处理关联

:::text
GET /tickets/12/messages- Retrieves list of messages for ticket #12
GET /tickets/12/messages/5- Retrieves message #5 for ticket #12
POST /tickets/12/messages- Creates a new message in ticket #12
PUT /tickets/12/messages/5- Updates message #5 for ticket #12
PATCH /tickets/12/messages/5- Partially updates message #5 for ticket #12
DELETE /tickets/12/messages/5- Deletes message #5 for ticket #12

如果这种关联和资源独立，那么我们可以在资源的输出表示中保存相应资源的endpoint。然后API的使用者就可以通过点击链接找到相关的资源。如果关联和资源联系紧密。资源的输出表示就应该直接保存相应资源信息

#使用SSL 使用SSL可以减少鉴权的成本：你只需要一个简单的令牌（token）就可以鉴权了，而不是每次让用户对每次请求签名。

#文档文档应该有展示请求和输出的例子：或者以点击链接的方式或者通过curl的方式
文档中应该有关于何时弃用某个API的时间表以及详情

#结果过滤，排序，搜索 url最好越简短越好，和结果过滤，排序，搜索相关的功能都应该通过参数实现

get /tickekts state=open

#限制API返回值的域使用fields查询参数来限制返回的域例如：

GET /tickets fields=id,subject,customer_name,updated_at&state=open&sort=-updated_at

#只提供json作为返回格式好读好用，逆袭xml成功

#API的输入数据格式使用json
很多的API使用url编码格式：就像是url查询参数的格式一样：单纯的键值对。这种方法简单有效，但是也有自己的问题：它没有数据类型的概念。这使得程序不得不根据字符串解析出布尔和整数,而且还没有层次结构。
如果API本身就很简单，那么使用url格式的输入没什么问题。但对于复杂的API你应该使用json。或者干脆统一使用json。
注意使用json传输的时候，要求请求头里面加入：Content-Type：application/json

#分页推荐将分页信息放到link header里面：
http://tools.ietf.org/html/rfc5988#page-6。

#鉴权 Authentication restful API是无状态的也就是说用户请求的鉴权和cookie以及session无关，每一次请求都应该包含鉴权证明。
通过使用ssl，可以不用每次都提供用户名和密码：我们可以给用户返回一个随机产生的token。这样可以极大的方便使用浏览器访问API的用户。这种方法适用于用户可以首先通过一次用户名-密码的验证并得到token，并且可以拷贝返回的token到以后的请求中。如果不方便，可以使用OAuth 2来进行token的安全传输。

#缓存 HTTP提供了自带的缓存框架。你需要做的是在返回的时候加入一些返回头信息

#出错处理就像html错误页面能够显示错误信息一样，API 也应该能返回可读的错误信息–它应该和一般的资源格式一致。
API应该始终返回相应的状态码，以反映服务器或者请求的状态。
API的错误码可以分为两部分，400系列和500系列，400系列表明客户端错误：如错误的请求格式等。500系列表示服务器错误。以json形式返回。错误应该包含以下信息：一个有用的错误信息，一个唯一的错误码，以及任何可能的详细错误描述。

:::text
{
  "code" : 1234,
  "message" : "Something bad happened :-(",
  "description" : "More details about the error here"
}

#附录：HTTP 状态码

:::text
 200 ok  - 成功返回状态，对应，GET,PUT,PATCH,DELETE.
 201 created  - 成功创建。
 304 not modified   - HTTP缓存有效。
 400 bad request   - 请求格式错误。
 401 unauthorized   - 未授权。
 403 forbidden   - 鉴权成功，但是该用户没有权限。
 404 not found - 请求的资源不存在
 405 method not allowed - 该http方法不被允许。
 410 gone - 这个url对应的资源现在不可用。
 415 unsupported media type - 请求类型错误。
 422 unprocessable entity - 校验错误时用。
 429 too many request - 请求过多。

#示例 github的api设计得非常好

##参考资料

RESTful API 设计最佳实践

文章作者种瓜

上次更新 2014-08-28

推荐订阅源

夜行人