差别

这里会显示出您选择的修订版和当前版本之间的差别。

--- public:it:restful [2016/11/22 14:39] – oakfire
+++ public:it:restful [2018/02/28 13:48] (当前版本) – 外部编辑 127.0.0.1
@@ 行 2: / 行 2: @@
 ===== Tools =====
   * API 接口设计工具: [[http://swagger.io/|swagger]], 支持 json/[[.:yaml|yaml]] 描述， 工具链最齐全。
-  * API 接口设计工具:[[http://raml.org/｜raml]], [[.: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]]