API 开发总结

自己总结：

1. 有版本控制
2. 新增的接口，虽然有一个同样的的控制器，一样新建一个，如果是更改原来接口，更改不多可以在原接口改，否则新增接口
3. 全部返回的数据如果前端可以自己计算就给他们计算，减少后端服务器压力

可以参考：

摘抄：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/

api的最佳实践

---

还是看open api吧

http://developer.github.com/v3/ 这个是github的接口写法

微博API

JSON API 设计参考文档，英文版1.0已经于近日完成
http://jsonapi.org/

中文版 文档还停留在2013年
http://jsonapi.org.cn/format/

最佳10条实践：
- https://blog.mwaysolutions.com/2014/06/05/10-best-practices-for-better-restful-api/
- http://www.startupcto.com/backend-tech/building-an-api-best-practices