====== RESTful ======
===== Tools =====
  * API 接口设计工具: [[http://swagger.io/|swagger]], 支持 json/[[.:yaml|yaml]] 描述， 工具链最齐全。
    * :!: swagger editor 工具， 如果 ''$ref'' 的值的格式错误，会出现不能定位到行的 error, 这时候只好一个个检查所有 $ref 的格式来甄别;
    * :!: 还是 swagger editor 工具， mac chrome 下输入汉字会出现字母与汉字齐飞，还未解决。  
  * API 接口设计工具: [[http://raml.org/|raml]], [[.:yaml|yaml]] 描述, 比较精简干练，但工具还不成熟。
  * API 框架: [[http://restify.com/|restify]], 效率上与express差不多， 但配套（throttling,监控）等比较方便。
  * API 检测工具：[[https://www.getpostman.com/|Postman]]
  * 数据校验(validation): [[https://www.npmjs.com/package/joi|joi]],   [[https://github.com/tlivings/enjoi|json-schema to joi]]
  * ACL 权限控制参考参考 [[https://www.npmjs.com/package/express-acl|express-acl]]
  * 认证 auth: HMAC Auth: [[http://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html|amazon s3 REST auth]]， 好像使用[[https://github.com/joyent/node-http-signature/blob/master/http_signing.md|http signing]] 比较好。 然后  restify 的自带插件有判断请求时间
===== Articles =====
  * [[http://www.infoq.com/cn/articles/understanding-restful-style|理解本真的REST架构风格]]
  * [[http://www.infoq.com/cn/articles/designing-restful-http-apps-roth|RESTful HTTP的实践]]
  * [[http://www.ruanyifeng.com/blog/2014/05/restful_api.html|阮一峰:RESTful API 设计指南]]

===== Notes =====
  * 在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词; 资源的 collection 用英文名词复数表示
===== 幂等(idempotence) =====
  * [[http://www.cnblogs.com/weidagang2046/archive/2011/06/04/2063696.html|理解HTTP幂等性]]

===== HTTP method 与返回 status code 涵义表 =====

HTTP verbs 涵义：
  * **GET**  /tasks - display all tasks
  * **POST** /tasks - create a new task
  * **GET**  /task/{id} - display a task by ID
  * **PUT**  /task/{id} - update a task by ID
  * **PATCH** /task/{id} - update some property of the task by ID
  * **DELETE** /task/{id} - delete a task by ID

通用状态码：
^ code ^ status ^ 涵义 ^
| 401 | Unauthorized | 用户没有权限（令牌、用户名、密码错误） | 
| 403 | Forbidden | 表示用户得到授权（与401错误相对），但是访问是被禁止的 |
| 404 | NOT FOUND | 用户发出的请求针对的是不存在的记录，服务器没有进行操作 |
| 405 | Method not found | 改资源不支持此方法的操作 | 
| 429 | Too Many Requests | 请求过于频繁 |
| 500 | INTERNAL SERVER ERROR | 服务器发生错误，用户将无法判断发出的请求是否成功 |
| 501 | Not Implemented | 接口未实现 |
| 503 | Service Unavailable | 服务器繁忙或维护，稍后再试 |

^ method ^ 涵义 ^ 安全 ^ 幂等 ^ code ^ status ^ status涵义 ^
| **GET** | 获取资源 | ✔ | ✔ | 200 | OK | 资源成功获取 |
|:::|:::|:::|:::| 202 | Accepted | 请求已进入队列（异步任务）|
|:::|:::|:::|:::| 406 | Not Acceptable | 用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式） |
|:::|:::|:::|:::| 416 | Requested Range Not Satisfiable | 参数超出范围 |
|:::|:::|:::|:::| 410 | Gone | 用户请求的资源被永久删除，且不会再得到的 |
| **PUT** | 更新资源 | ✘ | ✔ | 200 | OK | 资源已存在并成功修改 |
|:::|:::|:::|:::| 201 | Created | 资源成功创建 |
|:::|:::|:::|:::| 202 | Accepted | 请求已进入队列（异步任务） |
|:::|:::|:::|:::| 400 | INVALID REQUEST | 用户发出的请求有错误，服务器没有进行操作 |
|:::|:::|:::|:::| 422 | Unprocesable entity | 当创建一个对象时，发生一个验证错误 |
| **POST** | 创建子资源 | ✘ | ✘ | 201 | Created | 资源成功创建 |
|:::|:::|:::|:::| 202 | Accepted | 请求已进入队列（异步任务） |
|:::|:::|:::|:::| 400 | INVALID REQUEST | 用户发出的请求有错误，服务器没有进行操作 |
|:::|:::|:::|:::| 409 | Conflict | 资源已存在 |
|:::|:::|:::|:::| 422 | Unprocesable entity | 当创建一个对象时，发生一个验证错误 |
| **DELETE** | 删除资源 | ✘ | ✔ | 204 | NO CONTENT | 用户删除数据成功 |
|:::|:::|:::|:::| 202 | Accepted | 请求已进入队列（异步任务） |
|:::|:::|:::|:::| 400 | INVALID REQUEST | 用户发出的请求有错误，服务器没有进行操作 |

更多参考 [[https://tools.ietf.org/html/rfc7231#section-6|rfc7231]] 以及 [[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes|List of HTTP status codes]]