关于API的设计，一直没有找到很好的资料参考——大多数文章无非是只在介绍如何实现某种风格（如RESTful）API的技巧，缺乏深层次的思考和探讨，本文的聚焦点却在API设计本身上，关于技术，关于人性。
API既是前端与后端的约定，也是后端与其他端（如Python端）的约定，不同的端往往意味着不同的公司、系统、团队或者人，这决定了API的设计不仅仅是一个技术问题，还是一个社会协作问题。
简洁·适应·规范
从技术方面讲，有三点需要考虑：简洁性、适应性、规范性。
所谓简洁，就是API的入参没有任何冗余含混的多余字段，就如同数据库三范式那般，一方面是避免自相矛盾的数据，另一方面是使得API清晰易懂、调用方便。
API设计的社会性有时候会给这个目标带来阻力，比如API的提供者技能生疏，对字段间的传递函数依赖抱有怀疑态度，从而要求调用方传很多信息作为入参。
所谓适应，就是API要有一定的灵活性，能够在自身不需要变动的情况下应对新的调用模式和业务场景，这跟软件开发中的单一职责原则和高内聚低耦合的思想是一脉相承的。
提升适应性的两个技巧：
- 做成批量处理；
- 出参返回尽可能多的数据。
简洁性和适应性不是所有情况下都是融洽的：比如某个API执行一个业务操作，除了业务本身相关的参数，考虑到别的调用场景，还加了一些诸如来源、目的等可选参数，适应性提升了，简洁性却降低了。
所谓规范，就是约定俗成，比如入参和出参的格式、常用字段名称、异常状态码的惯例等，这一条对涉及与现有现有代码集成的API对接尤为重要，规范意味着高效和高质量，因为相关的处理逻辑都是现成且久经考验过的。
提升规范性的一个技巧：多参考已有API的设计。
代码逻辑守恒
如果数据前端能处理好再发给后端，那么后端就不用做低层次的处理了；如果Python端能提供批量处理图片的接口，那么后端就不用并发调用处理同步了。
就是这么简单。若把前端、后端、Python端看成一个整体，那么该有的代码逻辑就是得有，变数仅仅在于这个逻辑在什么地方。
代码逻辑守恒，但工作量并不守恒。
批量处理在Python端只是一个循环，但在后端就需要同步机构进行小心的处理；去除字符串的首尾空白字符在前端只是举手之劳，但在后端却意味着对核心业务逻辑的噪声和偏离。
人是有惰性的，同时又被自己的技能栈所局限，因此除了那些专业和有全局意识的人，大多数人在API设计时往往倾向于让对方多做事，自己少做事，把简单留给自己，把复杂推给别人。
不幸的是，由于代码逻辑守恒，一些明显不合理的设计决策最终却必然是能够实现的，从而就算有批评的声音，那些人以“能用就行”作为辩解居然也仿佛是正确的。
人性的弱点
没有人会蠢到说自己因为想偷懒才这个设计或让别人这么设计API，他们会打着性能（过早优化是一种罪恶）、领导说了、XX端是不可能（其实不一定真不可能，只是自己不肯，却偏偏表达上好像在说某种客观事实一样）、一直以来（一直以来如此懒惰）这些冠冕堂皇不好反驳的理由来提高自己观点的说服力。
听到这种话，也没什么可争的，由着他们来，自己默默写代码就是了，专业和不专业的差距不是一两句话能抹平的，撕破脸皮反而显得自己成了他们。
有的公司喜欢用告密这种方式来考评，在这种情况下，要尤其小心——技术上的争端会对绩效和晋升产生难以控制的不良影响——心胸狭窄的人是会背地里捅刀子的——心怀积怨，在领导面前说坏话。