我们厂有很多地方需要调用别人的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'
    }
}

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