既然有人看，那咱就分享一下

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