RESTful Api设计

拆分资源

  • ”资源“应该是个名词
  • 内部数据模型和资源对应起来
  • 不需要把它们一对一的都暴露出来。隐藏内部资源,暴露必需的外部资源。
  • 一旦定义好了要暴露的资源,你可以定义资源上允许的操作
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规则了

处理关联

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形式返回。错误应该包含以下信息:一个有用的错误信息,一个唯一的错误码,以及任何可能的详细错误描述。

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

附录:HTTP 状态码

 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设计得非常好

参考资料




Fork me on GitHub