对于维护API的经验，推荐《软件框架设计的艺术》这本书，无论是webService还是Rest还是其他什么，都很有帮助。
不过这书在概念上还是离平时工作太远，知识很精华，但和我的实际工作并不接轨，所以逐渐萌生“把我自己开发/运维API的一些经验整理出来，写一篇大的博文”这样的想法
不过最近又忙且病，所以一条条慢慢往外挤……
1. 参数命名规范
我曾经接手一个已经运行一段时间的API系统，它对外暴露的接口的参数，没有采用通用的第一个后单词首字母的规范
我在新开发接口时，决定采用新的规范；
但问题来了，接口的以前使用者，在调用新接口时，总也调不通，原因就是，以前用来标记访问来源的参数visitsystem，被我不经意间改成了visit**S**ystem，一字之差，接口在验证时找不到访问来源，于是不允许访问；
由此得出经验：参数规范化很重要，但对于以被使用的通用参数名，还是遵从以前的规则。
因为开发最不喜欢细看接口文档……啊啊啊！！！！（虽然我也有这毛病，但我还是要鄙视）
2. 接口返回值 对于错误信息的返回，非常重要。调用接口的系统，会根据错误信息，提示用户进行对应操作。 我负责这个系统，最开始是用数字（errcode），代表错误信息；但用数字用来标示每个错误，则粒度太细，用来标示一类错误，则对信息的提示又不足； 比如对于系统异常，和参数错误，是同级别的错误类型，和某个具体参数的具体错误，如email不符合规范，就不是同级别； 因而增加errMsg，填写具体错误信息（中文） 当然，系统架构上， 最好有对应的字典表，标记每个errcode对应哪类错误；
这种方式的优缺点如下： 优点：错误信息规范化，接口调用者可方便查询； 缺点：增加开发者工作量和运维量。
来源：oschina
链接：https://my.oschina.net/u/155755/blog/168341