API优先设计三原则

在与希望采用云开发和开放理念的开发人员交流中，经常会听到一个问题：“API优先”到底意味着什么？许多人认为“API优先”只是强调API的重要性，但并非必不可少。然而，真正的API优先设计远不止于此，它包含了三个核心原则。

API优先设计的三大核心原则

API优先思维的核心在于将API视为应用程序的第一个接口。换句话说，API的用户就是那些直接与API交互的开发者。因此，在设计API时，必须充分考虑这些开发者的需求。

API是产品功能的公开接口。如果某项功能未通过API提供，那么无论是图形用户界面（GUI）、命令行界面（CLI）还是语音界面，都无法访问该功能，这实际上使得功能“不可见”。因此，API的设计需要与产品功能紧密结合，确保所有功能都能通过API访问。

此外，API是用户与产品交互的最重要方式。因此，设计API时需要投入与设计图形用户界面同等的精力。API设计不仅要明确其功能，还要考虑其未来的扩展性和演进方式。

一旦认识到API是一个重要的接口，就会意识到它有自己的生命周期。随着应用程序的不断发展，功能会被优化、重构和扩展，但API的变化应当是缓慢且谨慎的。

可以用一个比喻来理解API的演进：如果将API视为产品的表面积，而功能是产品的体积，那么功能增加一倍，API的表面积仅增长25%。因此，API的设计需要从增长和灵活性的角度出发，确保其演进是优雅的。

优雅的API演进遵循以下原则：

此外，将API设计与实现解耦是至关重要的。尽管这可能会增加开发难度，但它能让API成为实现的契约和规范，而不仅仅是实现之上的一层薄薄的包装。

API优先设计的第三个原则是描述性。为了让API易于使用，它需要对未参与创建的开发者友好，这就离不开清晰的文档。

高质量的API文档是使API对人类开发者可用的必要条件。尽管自动化工具和AI技术正在进步，但编程仍然是由人类主导的活动，因此文档的重要性不容忽视。

在文档编写方面，结构化文档优于非结构化文档。遵循标准化的模式（如URL、资源类型、请求方法、头信息、请求参数和响应格式）可以帮助开发者更轻松地探索和理解API功能，同时减少API增长过程中可能出现的意外问题。

在API设计中，应尽量减少意外行为，遵循既定的标准和最佳实践。当无法完全遵循时，应记录偏差，以避免API消费者因行为与预期不符而浪费时间。

原文链接: https://blog.developer.adobe.com/three-principles-of-api-first-design-fa6666d9f694