目录

RESTful

RESTful

Tools

API 接口设计工具: swagger, 支持 json/yaml 描述，工具链最齐全。
- swagger editor 工具，如果 $ref 的值的格式错误，会出现不能定位到行的 error, 这时候只好一个个检查所有 $ref 的格式来甄别;
- 还是 swagger editor 工具， mac chrome 下输入汉字会出现字母与汉字齐飞，还未解决。
API 接口设计工具: raml, yaml 描述, 比较精简干练，但工具还不成熟。
API 框架: restify, 效率上与express差不多，但配套（throttling,监控）等比较方便。
API 检测工具：Postman
数据校验(validation): joi, json-schema to joi
ACL 权限控制参考参考 express-acl
认证 auth: HMAC Auth: amazon s3 REST auth，好像使用http signing 比较好。然后 restify 的自带插件有判断请求时间

Articles

Notes

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词; 资源的 collection 用英文名词复数表示

幂等(idempotence)

理解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	用户发出的请求有错误，服务器没有进行操作

更多参考 rfc7231 以及 List of HTTP status codes