restful api

阅读材料

1. http://www.ruanyifeng.com/blog/2014/05/restful_api.html 
2. http://www.ruanyifeng.com/blog/2011/09/restful.html
3. http://blog.jobbole.com/41233/
4. http://www.ibm.com/developerworks/cn/web/1103_chenyan_restapi/
5. http://wenku.baidu.com/view/277d37d484254b35eefd347d.html
6. http://www.cnblogs.com/artech/p/restful-web-api-02.html
7. http://www.oschina.net/translate/best-practices-for-a-pragmatic-restful-api

google能搜索到的前几名都在这了.

前面的例子, 只反应了对 单个 uri的 处理. api不一样, 是一套,成系统的,等级明确的uri. 规则和秩序是伟大的发明,能有效的组织起事物.设计, 就是关于如何组织和创造的学问.

按 1号材料, 这里面设计到 

1. 协议
2. 域名
3. 版本
4. 终点
5. 动词
6. 过滤
7. 状态码
8. 错误处理
9. 返回结果
10. 内置文档
11. 鉴权等其他

因为现在是学习,所以, 协议暂时先用 http, 域名直接用ip/api,版本就v1吧,鉴权先不搞,数据来往尽量json,文档什么的也不说. 说剩下的几个.

首先是重点, uri 的设计,这里就是字符串, 什么都行, 但是 非ascii的估计会被重新编码,所以,最好还是保证ascii. 

uri 可以用 '/' 来分段, 那么  这里, 第一段最好是 种类, 第二段才放id.

• GET /collection：返回资源对象的列表（数组）
• GET /collection/resource：返回单个资源对象
• POST /collection：返回新生成的资源对象
• PUT /collection/resource：返回完整的资源对象
• PATCH /collection/resource：返回完整的资源对象
• DELETE /collection/resource：返回一个空文档

get 一个种类时候, 就返回他所有对象的列表.简单可以理解为, 种类是一个概念, 然后, 返回的是他的外延.

get 一个种类下具体资源, 那就返回这个资源.

post 是新建, 比如新摆上一台桌子.

put 则是完整修改一个东西,比如把3号桌客人给换成这几位爷.

patch 是把3号桌南首那个位子的人给换成这位小哥

delete 是 来人啊,把这桌子给我撤了

种类是个很宽泛的概念, 他不是实体, 实际上只是一个空位,一个集合概念,在这也就是相当于一个桌子.

当进行一个活动时候, 不一定会成功.可能会出现错误. 比如, get /桌子/3  把3号桌给我报上来.

然后, 小二发现没有 3号桌. 只好回答说 找不到 404

 因为客人来来往往的比较多,人类语言的不精确性容易出问题,所以,大家建了一个标准的巴别塔.用数字来表示意译.就像搬砖游戏里,指指红色就知道是红砖, 看到数字404 也能知道, 哦, 找不到.这其实是个翻译过程

找到了怎么办, 发 200 .然后把东西送过来.

post/put/patch 这一类要换人或者摆桌子的行动, 成功了, 那就是回答 201. 好了,客官,您吩咐的事儿已经办成了.

删除办成了,叫 204.

其他的还有, 比如 收到一个 put afouelf好哦 谁都读不出来的东西, 那就指指耳朵, 对不起, 我听不懂.400.

您会中文么?

小二去执行命令时候摔了一跤,头破了,不能继续, 就500,客官,这个我干不了了.我出事儿了.

反正内容到真是不算多, 但想做好, 好难的还是. 比如写字, 人人都会,丑不丑, 那就得看天分和练习了.