Heroku团队根据heroku platform api和他们自己内部系统的实践经验总结了一些http api设计的准则,发布到了github上。
地址:

https://github.com/interagent/http-api-design

鉴于见到太多公司的http接口没有按照标准规范来实施,推荐做服务接口设计和前端的同学都看看。

其中很重要的几条抽出来:

  • 返回正确的状态代码

不要始终使用200! 201,202对应不同的METHOD是很有意义的。 出现错误是应该返回正确的状态码,是请求参数错误请返回400,是服务器内部出错请返回500,服务器压力过大需要kill连接请返回503,对于行为错误而不是权限问题不要使用401而要用403。这些状态代码本身都有意义,不需要去而外的创建代码或者用额外的属性。

  • 以ISO8601格式来使用UTC时间

记得使用UTC,同时格式统一,真的需要在每个项目里面去引用moment.js来处理时间?时区和格式足够头痛了,moment.js也不是万能的。

  • 给出结构化的错误信息

错误不要只返回给状态吗,能够给出一定错误信息的情况下要在body中返回统一的结构化的错误信息。这样客户端也可以做出正确的处理,是等待之后重试还是停止请求通知用户。

当然还有很多就不一一细列了。去看heroku团队的指南吧