RESTful架构---实践

本文不求完全细致，只求看到这些东西的时候还能想起来那么一回事
本文内容部分摘自网络，主要参考阮一峰老师的文章

• API的关键要求:
  
  • 当标准合理的时候遵守标准。
  • API应该对程序员友好，并且在浏览器地址栏容易输入。
  • API应该简单，直观，容易使用的同时优雅。
  • API应该具有足够的灵活性来支持上层ui。
  • API设计权衡上述几个原则。
• 使用RESTful URLs 和action.
  
  • 即 将API在逻辑上区分为资源.并且能够通过http的get,post,put,delete来进行操作.
• 如何拆分这些资源呢?
  
  • 这里的关键是隐藏内部资源，暴露必需的外部资源。
  • 一旦定义好了要暴露的资源，你可以定义资源上允许的操作，以及这些操作和你的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 状态码