代码是IT公司的核心资产,API是代码对外的展现形式,编写友好的RESTful API不论对于你的同事，还是将来作为第三方服务调用接口的用户来说，都显得至关重要.一家拥有好的API设计的公司往往在开发效率,代码质量上占有明显的优势.

API设计的基本原则：

API Should Do One Thing and Do it Well
- 坚持K.I.S.S原则,保持合理的API粒度,一个接口只做一件事,只做最基本,最原子的事. 然后做好它.这有助于实现高度正交性的API集合
API Should Be As Small As Possible But No Smaller
- API因为简洁而优雅,但是不为了简洁而强行简洁.
  - RESTFul API的路径命名要尽量的简短但是不要过度精简而失去可读性
  - API的功能的边界要自行把握,不能过于混合了各种功能而庞大难用,也不能因为功能过度单一而使前端需要过多次数的请求
Implementation Should Not Impact API
- API的设计和代码的实现无关,完全解耦.我们可以使用不同的语言(Java/Go/Python/Node)来实现同时能在不同的计算平台上运行(serverless/container/bare metal server)
Minimize Accessibility of Everything
- 对安全重视,对资源有最小化的访问权限
Names Matter–API is a Little Language
- API的header,path,paramter,method,body里面的参数的命名和设计很重要,它们形成一种风格
Documentation Matters
- API的文档和重要,最好有集中保持的地方
API Must Coexist Peacefully with Platform
- API必须与平台和平共存,能够随着业务需求的变化而变化.API能够可扩展可迭代而不是阻碍平台的发展

API设计人员视角

安全是第一优先级,全部的交付使用的API都必须为HTTPS而不是不安全的HTTP.
开发团队/公司有统一的API风格.这有助于形成开发人员见的默契提升API的开发效率并形成统一的规范和开发流程.
API定义可读性非常重要,能够见名知义的API往往比过度简介的API更能被开发人员理解并正确使用.如果你无法用简单描述API功能，也许你设计的API是错误的.如何检验API设计是否清晰：需要把它放在真正的使用场景来检验.
- 所有单词避免模糊
- 删除无需要的单词
- 依据角色/功能进行命名
最好是符合RESTFul规范,并进行了精心的设计.
API容易迭代,容易迭代,对后续可能的版本变更有一定的适应能力

参考资料: