我们厂有很多地方需要调用别人的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'
}
}
暂时告一段落，后面想到了继续修改。
