2019独角兽企业重金招聘Python工程师标准>>> 
既然有人看，那咱就分享一下
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
- go的类似sinatra的框架beego
开发最佳实践
- api的code和msg可以写一个gem，直接继承到api里
- api测试和mock，最好是可以先mock出静态的，可以api和mobile端同时开发
- 根据测试生成api文档
不过我还没有发现好的实现，还请各位指点
api的最佳实践
还是看open api吧
- http://developer.github.com/v3/
- 微博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
这是去年我在ruby-china发的总结，转过来给大家看看
原文地址：https://ruby-china.org/topics/15173
欢迎关注我的公众号【node全栈】 