标签：
既然有人看，那咱就分享一下 ## API 标准写法 摘抄：http://www.startupcto.com/backend-tech/building-an-api-best-practices You‘ll generally want to wrap all your API responses in an ‘envelope‘ which specifies metadata about the APIcall. ``` // sample JSON envelope { "status": { "code": 10000, "message": ‘Success‘ }, "response": { ...results... } } ``` Doing this allows for client handler code to behave the same way for all API calls, since it gets a responses back in a universal format. 语义上再好一点，推荐： ``` // sample JSON envelope { "status": { "code": 10000, "message": ‘Success‘ }, "data": { ...results... } } ``` 可视化编辑校验： http://jsoneditoronline.org/ ## 注意事项 - json一定要规范，不然ios的json库无法读 - 如果支持jsonp，自己再加上一个callback就可以了。 - 状态码说明：code：10000类似的，要以业务或者功能模块来分类，以便debug的时候快速定位 - 尽量遵守rest ## 解释一个问题 http://ruby-china.org/topics/15164#reply5 ``` xiaogui 7楼 , 19小时前 喜欢 #5楼 @lytsingsun 先说几点个人建议吧： 1、返回 json 数据，最好外面包一层校验，能让客户端快速知道，这数据合不合法、是否有错； 2、代码复用方面，主要看你项目的实际情况； 3、最好是能给客户端进行充分的沟通，怎么让双方都正规还方便； 4、性能方面，不外乎负载均衡、上缓存、数据库读写分离、代码优化； ``` 第一点：就是说上面返回的status，要有code和message，根据code来判断问题，一般会直接alert出来code：message或者在日志里 这是xiaogui说的外面包一层校验的意思 其他的就没啥需要特殊说明的了 ## 关于http的状态码和api里的status.code说明 **http的状态码是直接在request里的，这个一般指服务器的状态，api是假设每一个请求都是200的，在客户端非200的请求统一处理异常，而200的请求，首先解读status获取code是否为0（假设0是请求正确返回），如果是0就读取data，继而完成相应业务逻辑处理。** - 职责单一，该是server的就是server，该是业务逻辑的就是业务逻辑的 - 少用http状态码，把http状态码统一封装到一个类，用于处理异常情况（ajax也好，ios的asi或afnetworking也好） - 同样可以表示状态的，优先自定的状态码 ## 为什么在response json里没有必要加http status code 每一个request都可以获得状态码，而上面我给出的json是在response里，那么在在http请求完成的时候我们仍然可以获得此request的所有信息 如果仍然在response里加入request里的东西，这样做是重复的，真的是没有必要的，not DRY 换个角度讲，一般我们使用http库的时候要自己封装处理http status code的，尽力减少每个请求的代码，是不可能每个request都去 ``` 判断code==200.。。。。。然后。。。。。 ``` ## 技术选项 - express or koa - rails-api - grape - [sinatra](http://sinatrarb.com/) - go的类似sinatra的框架[beego](http://beego.me/) ## 开发最佳实践 - api的code和msg可以写一个gem，直接继承到api里 - api测试和mock，最好是可以先mock出静态的，可以api和mobile端同时开发 - 根据测试生成api文档 **不过我还没有发现好的实现，还请各位指点** ## api的最佳实践 还是看open api吧 - http://developer.github.com/v3/ - [微博API](http://open.weibo.com/wiki/微博API) ---------------------- ## 当。。。。 ### 关联优先 比如获取新闻接口返回数据如下： ``` { "data": [ { "nid": 2, "mid": 1, "text": "this is a test.", "images": [ "http://121.199.40.172:8086/images/news/12.png", "http://121.199.40.172:8086/images/news/13.png", ... ], "videos": [ "http://121.199.40.172:8086/videos/news/12.amr", "http://121.199.40.172:8086/videos/news/13.amr", ... ], "like": 0, "comment": 0, "publish_time": "2013-01-01 12:30:10" }, ... ], "status": { "code": "0", "msg": "success" } } ``` 返回的对象数组，乍看是合适的，但是我们发现1条新闻对应着多个评论，如果评论没有出现在此接口中，我就要发一个新的请求，这样问题就来了，该不该呢？ 个人觉得，好的api，如果一次news的数据不是特别多，就应该最新评论，如5条，10条的带上 ## 更新: 使用cors解决跨域问题 使用cors，解决跨域问题，实际中也是这样用，不过app.js里配置的路由还需要更严谨 ``` // 支持跨域 app.use(require(‘cors‘)()); ``` 一般移动测试都要起一个server，然后访问api服务器的时候就要跨域，这样就可以在移动端浏览器里测试了。 而phonegap打包的时候是本地html所以不用跨域，但是为了测试方便，服务器还是建议加上cors。 - [best-practices-for-a-pragmatic-restful-api](http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api) ------------ 这是去年我在ruby-china发的总结，转过来给大家看看 原文地址：https://ruby-china.org/topics/15173 欢迎关注我的公众号【node全栈】 标签：
原文地址：http://my.oschina.net/nodeonly/blog/468643
