什么是API设计？

API设计是就API如何向消费者公开数据和功能做出有意决策的过程。成功的API设计以标准化规范格式描述API的端点、方法和资源。

API设计过程通过确保API支持业务目标，同时保持易于使用、适应性、可测试和文档齐全，从而使消费者和生产者都受益。API设计应在API生命周期的早期进行，以实现关键利益相关者之间的一致性，并帮助团队在问题根深蒂固之前识别问题。API设计也是有效API治理策略的重要组成部分，因为它有助于团队标准化可以在整个组织中重复使用的API模式。

API设计如何支持API优先开发模型？

API优先是一种开发模型，其中应用程序通过API交付的服务进行概念化和构建。采取代码优先方法的公司可能会将API视为事后的想法，而API优先公司在开发应用程序之前会设计其API。该策略使消费者和生产商能够在构建实现之前就API定义进行协作，从而提高了API的质量和可用性。

API设计的关键阶段是什么？

在API设计过程中，每个组织都应该遵循四个关键步骤。每一步都需要利益相关者（如商业领袖、开发人员、消费者和合作伙伴）之间的协作，以确保API满足所有相关需求。在API设计过程的每一步进行协作也有助于开发人员避免构建不必要的功能。这些步骤是：

步骤1：确定API打算做什么

API设计过程的第一步是让所有利益相关者就API的业务用例达成一致。负责身份验证工作流程的API与允许用户浏览产品目录的API有不同的要求，因此在做出任何其他决定之前，对齐用例很重要。用例也可能影响您选择的架构类型。例如，基于gRPC的架构对于连接内部微服务的API来说可能最有意义，而GraphQL API非常适合依赖不同数据源的服务。一旦达成一致，利益相关者应该通过用自然语言描述它如何满足特定需求来明确概述他们对API的目标。

第2步：用规范定义API合同

一旦所有利益相关者都对API的用例达成一致，您将需要决定哪些资源，他们的数据应该如何格式化和结构化，他们应该如何相互关联，以及哪些方法应该在其相关端点上可用。确定API中所需的抽象和封装水平也很重要，这将帮助您在可重用性和可读性之间取得平衡。

这些决策应该被捕获在API定义中，这是API预期功能的人机可读表示。API定义遵循API规范，如OpenAPI和AsyncAPI，它们为API定义提供了标准化格式，并为API合同、文档、模拟和测试奠定了基础。

第3步：用模拟和测试来验证你的假设

完成API定义后，您可以使用它来生成模拟服务器。模拟服务器响应请求返回样本数据，这使您能够确认您的API将按您的意愿工作。模拟也可以与API测试一起使用，API测试可以手动、按计划运行，也可以在CI/CD管道中自动运行。在API设计过程中进行测试和嘲笑将帮助您在问题进入消费者的代码库之前发现和补救任何问题，因为这些问题更难修复。

第4步：记录API

API设计过程的最后一步是编写文档。此步骤涉及定义有关每个资源、方法、参数和路径的关键细节，有助于验证设计，并确保消费者能够尽快开始使用您的API。文档还可能包括API请求和响应的示例，这让消费者深入了解特定API如何支持常见业务需求。一些工具可以从API定义自动生成文档，因此团队不必担心他们的文档会过时。

有哪些API设计最佳实践？

每个API都是不同的，因此需要独特的API设计方法。尽管如此，无论API的架构、语言或用例如何，您都应该始终牢记几个最佳实践。例如，重要的是：

• 优先考虑一致性：一致性是成功API设计的关键要素，因此领导者必须制定API治理战略，以促进全组织标准。例如，组织投资组合中的每个API都应该对每个方法、端点和资源使用一致的命名约定。
• 收集每个利益相关者的意见：API设计问题通常源于沟通不畅。每个利益相关者都可能拥有特定领域的知识，这些知识可能会影响API的设计和实施，并且应该将他们包含在每次对话中。
• 了解API的上下文和约束：团队在做出任何设计决定之前，必须清楚地了解API的上下文和约束。例如，重要的是要考虑相互竞争的项目时间表、底层系统的局限性以及预期的流量。这些知识将使团队能够做出明智的决策，为API的成功做好准备。
• 把REST API设计约定落实为开发规范。

参考资料

英文原文：API Design