本文不求完全细致,只求看到这些东西的时候还能想起来那么一回事
本文内容部分摘自网络,主要参考阮一峰老师的文章
- API的关键要求:
- 当标准合理的时候遵守标准。
- API应该对程序员友好,并且在浏览器地址栏容易输入。
- API应该简单,直观,容易使用的同时优雅。
- API应该具有足够的灵活性来支持上层ui。
- API设计权衡上述几个原则。
- 使用RESTful URLs 和action.
- 即 将API在逻辑上区分为资源.并且能够通过http的
get,post,put,delete
来进行操作.
- 即 将API在逻辑上区分为资源.并且能够通过http的
- 如何拆分这些资源呢?
- 这里的关键是隐藏内部资源,暴露必需的外部资源。
- 一旦定义好了要暴露的资源,你可以定义资源上允许的操作,以及这些操作和你的API的对应关系:
GET /tickets
# 获取ticket列表
GET /tickets/12
# 查看某个具体的ticket
POST /tickets
# 新建一个ticket
PUT /tickets/12
# 更新ticket 12.
DELETE /tickets/12
#删除ticekt 12
可以看出使用REST的好处在于可以充分利用http的强大实现对资源的CURD功能
使用复数还是单数
虽然看起来使用复数来描述某一个资源实例看起来别扭,但是统一所有的endpoint,使用复数使得你的URL更加规整。
如何处理关联?关于如何处理资源之间的管理REST原则也有相关的描述:
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
- 不符合CRUD的操作.
重构你的行为action。当你的行为不需要参数的时候,你可以把active对应到activated这个资源,(更新使用patch).
以子资源对待。例如:github上,对一个gists加星操作:PUT /gists/:id/star
并且取消星操作:DELETE /gists/:id/star
.
有时候action实在没有难以和某个资源对应上例如search。那就这么办吧。我认为API的使用者对于/search
这种url也不会有太大意见的(毕竟他很容易理解)。只要注意在文档中写清楚就可以了。 - 安全性
OAuth 2 认证. 文档
版本化
对外公开的API要兼容以前版本的内容.- 结果过滤,排序,搜索
这些都应该通过参数实现. - 限制API返回值的域
API使用者可能并不需要所有的结果,可以提供一个fileds字段来区分使用者要返回哪些字段. - 更新和创建操作应该返回资源
更新完成或者创建完成后,应该返回对应的资源. - 是否需要 “HATEOAS“
有待研究 - 只提供json作为返回格式
- 如果使用json最好遵循JavaScript的命名方法.使用驼峰命名法
- 默认使用
pretty print
格式,使用gzip
fastjson只能通过toJsonString
方法在将对象转化为json样式的字符串时有一个prettyFormatter
参数. - 只在需要的时候使用“envelope”
{
"data" : {
"id" : 123,
"name" : "John"
}
}
- 在post,put,patch上使用json作为输入
在请求头中加入Content-Type:application/json
- 分页
- 自动加载相关的资源
可以再url参数中追加一个embed或者expend,表示要自动加载的相关资源. 注意不要产生N+1 select
的问题 - 重写HTTP方法
- 速度限制
- 为什么使用当前时间段剩余秒数而不是时间戳?
- 鉴权 Authentication和安全性冲突了吧
缓存
HTTP提供了自带的缓存框架。你需要做的是在返回的时候加入一些返回头信息,在接受输入的时候加入输入验证。基本两种方法:
ETag
:当生成请求的时候,在HTTP头里面加入ETag
,其中包含请求的校验和和哈希值,这个值和在输入变化的时候也应该变化。如果输入的HTTP请求包含IF-NONE-MATCH
头以及一个ETag
值,那么API应该返回304 not modified
状态码,而不是常规的输出结果。Last-Modified
:和etag
一样,只是多了一个时间戳。返回头里的Last-Modified
:包含了 RFC 1123 时间戳,它和IF-MODIFIED-SINCE
一致。HTTP规范里面有三种date格式,服务器应该都能处理。
出错处理
api应该返回刻度的错误信息,至少要将400系列的错误信息以json格式返回.- HTTP 状态码