Http API设计规范思考

我们厂有很多地方需要调用别人的API,也有很多地方被别人调用。在这个过程,有些点让人很难受,也有些让人有了深刻的领悟。

难受的点

  • xml格式的报文
  • 更有甚者WebService这种重量级的报文
  • 错误信息完全无意义
  • 报文中格式混乱,完全不必要的嵌套

深刻的领悟

  • 你用着不舒服的地方一定不要拿来继续折磨别人
  • json没什么比xml差的地方
  • 错误码,错误信息一定谣给全,不管是调试阶段还是线上生产环境,一个完全无意义的错误码和消息,会让调用者开启脏话模式
  • 报文结构统一,不涉及出3层以上的嵌套数据

暂时想到的是这么些点。
本人有幸在我们厂的一个项目上设计对外的API,就拿出自己的设计和各位来探讨下。

写在之前

尽量用Https吧,这时趋势。

用户信息或者token

用户加密信息或者token之类的信息不要放在报文里面了,直接放入head,本来按照http的规范,这里就是放置这些信息的地方

url定义

尽量按照restful来,这样起码你的url可以一目了然地说明你接口作用。
GET HTTP1.1 http://www.xxx.com/user/{id}
这种接口,只要是熟练工,都知道是啥意思。

版本信息放入到url吧,这样还可以用nginx做路由。

比如 GET HTTP1.1 http://www.xxx.com/{version}/user/{id}

request参数

在post或者put之类地请求中会有参数传入进来,用json吧.
比如

{
  'date': '2017-02-28 00:22',
  'no': 'xxxxxxxxxx',
  'clientType': 'iphone',
  'params': {
    'foo': 'bar'
  }
}

response信息

json吧,真心地,数据量小,结构优良,也易于观察

{
    'date': '2017-02-28 00:27',
    'no': 'xxxxxxxx',//流水号
    'code': '0',//一定要有一个消息地code字典
    'msg': 'xxxx'//一定是对该业务和该错误有帮助地话语,然后要说人话
    'data': {}
}

其中data的数据会有两种情况,都是接口文档说明,一种是返回多条数据时,一种是单结果时。
多结果

{
        'page': 1,
        'pageSize': 1,
        'count': 100,
        'items': [{
            'foo': 'bar'
        }]
    }

单结果

{
    'item': {
        'foo': 'bar'
    }
}

暂时告一段落,后面想到了继续修改。

IT文库 » Http API设计规范思考
分享到: 更多 (0)

评论 抢沙发

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址