關於API的設計，一直沒有找到很好的資料參考——大多數文章無非是隻在介紹如何實現某種風格（如RESTful）API的技巧，缺乏深層次的思考和探討，本文的聚焦點卻在API設計本身上，關於技術，關於人性。
API既是前端與後端的約定，也是後端與其他端（如Python端）的約定，不同的端往往意味着不同的公司、系統、團隊或者人，這決定了API的設計不僅僅是一個技術問題，還是一個社會協作問題。
簡潔·適應·規範
從技術方面講，有三點需要考慮：簡潔性、適應性、規範性。
所謂簡潔，就是API的入參沒有任何冗餘含混的多餘字段，就如同數據庫三範式那般，一方面是避免自相矛盾的數據，另一方面是使得API清晰易懂、調用方便。
API設計的社會性有時候會給這個目標帶來阻力，比如API的提供者技能生疏，對字段間的傳遞函數依賴抱有懷疑態度，從而要求調用方傳很多信息作爲入參。
所謂適應，就是API要有一定的靈活性，能夠在自身不需要變動的情況下應對新的調用模式和業務場景，這跟軟件開發中的單一職責原則和高內聚低耦合的思想是一脈相承的。
提升適應性的兩個技巧：
- 做成批量處理；
- 出參返回儘可能多的數據。
簡潔性和適應性不是所有情況下都是融洽的：比如某個API執行一個業務操作，除了業務本身相關的參數，考慮到別的調用場景，還加了一些諸如來源、目的等可選參數，適應性提升了，簡潔性卻降低了。
所謂規範，就是約定俗成，比如入參和出參的格式、常用字段名稱、異常狀態碼的慣例等，這一條對涉及與現有現有代碼集成的API對接尤爲重要，規範意味着高效和高質量，因爲相關的處理邏輯都是現成且久經考驗過的。
提升規範性的一個技巧：多參考已有API的設計。
代碼邏輯守恆
如果數據前端能處理好再發給後端，那麼後端就不用做低層次的處理了；如果Python端能提供批量處理圖片的接口，那麼後端就不用併發調用處理同步了。
就是這麼簡單。若把前端、後端、Python端看成一個整體，那麼該有的代碼邏輯就是得有，變數僅僅在於這個邏輯在什麼地方。
代碼邏輯守恆，但工作量並不守恆。
批量處理在Python端只是一個循環，但在後端就需要同步機構進行小心的處理；去除字符串的首尾空白字符在前端只是舉手之勞，但在後端卻意味着對核心業務邏輯的噪聲和偏離。
人是有惰性的，同時又被自己的技能棧所侷限，因此除了那些專業和有全局意識的人，大多數人在API設計時往往傾向於讓對方多做事，自己少做事，把簡單留給自己，把複雜推給別人。
不幸的是，由於代碼邏輯守恆，一些明顯不合理的設計決策最終卻必然是能夠實現的，從而就算有批評的聲音，那些人以“能用就行”作爲辯解居然也彷彿是正確的。
人性的弱點
沒有人會蠢到說自己因爲想偷懶才這個設計或讓別人這麼設計API，他們會打着性能（過早優化是一種罪惡）、領導說了、XX端是不可能（其實不一定真不可能，只是自己不肯，卻偏偏表達上好像在說某種客觀事實一樣）、一直以來（一直以來如此懶惰）這些冠冕堂皇不好反駁的理由來提高自己觀點的說服力。
聽到這種話，也沒什麼可爭的，由着他們來，自己默默寫代碼就是了，專業和不專業的差距不是一兩句話能抹平的，撕破臉皮反而顯得自己成了他們。
有的公司喜歡用告密這種方式來考評，在這種情況下，要尤其小心——技術上的爭端會對績效和晉升產生難以控制的不良影響——心胸狹窄的人是會背地裏捅刀子的——心懷積怨，在領導面前說壞話。