本文探讨了API优先方法的定义及其与其他API开发方法的比较，包括代码优先和设计优先方法，强调了选择合适方法的重要性及其优缺点。

https://document360.com/blog/api-first-approach/

API-First 是少数 API 开发方法之一。因此，让我们定义什么是“API 开发方法”并探索可用的选项。

API开发方法是设计、开发、部署和管理API（应用程序编程接口）的方法。它提供了创建 API 的框架，包括规划、记录、实施、测试和维护。三种最常用的 API 开发方法是：

您不需要单独采用这些方法。相反，您可以使用更适合您的项目要求的变体或混合方法。

最后，您应该根据项目复杂性、团队动态、需要多少前期规划、需求灵活性和集成需求来选择方法。

深入探讨：API 开发方法

方法#1：代码优先

API 开发的代码优先方法涉及通过代码设计和实现 API。 API 规范是在构建 API 之后制定的。

开发人员跳过正式的设计阶段。相反，它们解释定义 API 端点、请求/响应模式和业务逻辑的基本要求。然后，他们使用OpenAPI等工具和框架来生成 API 规范、文档和其他工件。

使用这种方法，“代码”是 API 规范的唯一真实来源。

以下是代码优先方法的概述：

重点：

* 通过编码设计API并稍后生成相关工件。

好处：

* 没有设计阶段来减慢开发速度。
- 开发团队可以随着项目需求的变化自由地实施变更。

API 规范与 API 实现紧密结合。

挑战：

* 团队之间缺乏清晰、有效的沟通、一致性和协调。
- 在开发过程中进行更改比在设计阶段进行更改的成本更高。

以下是 Code-First 关键组件的概述：

通过代码进行设计

开发人员不是从正式的 API 规范或设计文档开始，而是从编写实现 API 端点和相关逻辑的实际代码开始。然后，他们定义 API 的请求/响应模型、身份验证机制以及代码的其他方面。

框架和注释

开发人员使用框架和库用 API 详细信息注释代码。这些框架可以解析代码并生成 API 规范。根据该规范，他们使用Swagger等工具来生成API 文档、客户端 SDK 和工件。自动化有助于确保一致性并减少维护文档的手动工作量。

迭代开发

这种方法非常灵活，因为它允许开发人员迭代 API 的设计并快速进行更改，从而缩短开发周期。

与实施的紧密结合

在 API 需要与实现需求和底层业务逻辑紧密结合的场景中，API 代码和规范之间的紧密耦合是有益的。

方法#2：设计优先

设计优先是一种协作方法，来自各行各业的利益相关者可以使用“对每个人都有意义”的语言和工具参与设计 API。编写规范发生在开发之前，甚至在编写规范之前就有一个“设计”阶段。利益相关者通过使用“高级”语言解释基本要求，从概念上映射 API 的功能。

一旦需求准确并且得到各方的认可，团队就可以解释项目需求，以使用图形工具创建 API 的结构、端点和数据格式。

请注意，在整个过程中，开发人员和非开发人员合作完善规范。

以下是代码优先方法的概述：

重点：

* 跨职能利益相关者在编写代码之前预先设计并记录 API 规范。
- API 规范在开发过程中充当合同。

好处：

* 通过对 API 规范的共同理解，实现清晰一致的团队沟通。
- 前端和后端团队可以并行工作。
- 在设计阶段进行更改的成本更低。

挑战：

* 前期设计工作和团队协调是资源密集型的。
- 跨职能沟通的延迟和官僚机构的层级可能会减慢事情的进展。

以下是 Design-First 关键组件的概述：

广泛的设计阶段

包括开发人员在内的利益相关者必须使用“共享语言”进行沟通。

开发人员和非开发人员使用一组共享工具进行协作，其中通常包括可视化 API 设计工具。然后，他们可以生成机器可读格式的开放 API 规范。

合同规格

API 规范成为所有相关利益相关者 API 开发过程的唯一事实来源。因此，API 的更改需要所有利益相关者的支持。

文档

API 规范充当 API 的设计合同和文档。使用设计优先的方法，团队可以在 API 规范中彻底记录他们的 API。这项工作需要协作来确定需求、功能和预期行为。

验证和模拟

采用规范语言允许您使用工具根据标准、最佳实践和错误来验证和测试 API 规范。模拟工具可以根据规范生成模拟响应。客户端开发人员可以开始使用虚假 API，提供早期反馈机会。

当然，您可以使用代码优先方法来实现原型和模拟。但是，Design-First 仅需要您的规范，而 Code-First 则需要 API 实现代码。

方法#3：API 优先

公司可能提供多种产品和服务。然而，API 优先的公司将 API 视为将所有其他产品粘合在一起的最关键产品。因此，他们首先优先考虑其发展。

以下是 API 优先方法的概述：

重点：

* 优先考虑 API 开发而不是其他软件组件
- 创建一个 API 生态系统，其中每个 API 都发挥特定作用

好处：

* 跨 API 的一致开发者体验
- API 独立发展并减少依赖性
- 标准定义系统组件的交互

挑战：

* 需要宣传来传达为什么企业应该优先考虑 API
- 缺乏与前端团队的并行开发

以下是 API-First 关键组件的概述。

顺序

API 是连接您可以与之交互和交换数据的所有独立软件、服务或应用程序的主要接口。因此，API 优先的企业在依赖 API 的服务、组件和用户界面之前构建 API。

相反，设计优先和代码优先可能不会优先于其他组件构建 API。例如，团队可能希望在制作 API 的同时创建用户界面。

模块化和可重用性

在 API 优先的情况下，每个 API 都被视为 API 生态系统中的“产品”。因此，团队可以使用他们认为最适合 API 的技术堆栈来构建 API。此外，API 可以通过保持独立于产品组合中的其他 API 来发展和改进。

互操作性

API优先强调标准化，从开发API规范作为集成外部服务、第三方平台或开发者生态系统的接口开始。

开发者体验 (DX)

每个 API 都在组织的整个 API 生态系统中实现特定目的。这种方法与在没有整个产品“清晰愿景”的情况下开发不同 API 的趋势形成鲜明对比。由于一致性，结果是更好的开发人员体验。

准备好将您的 API 文档提升到新的水平了吗？今天和Baklib一起！

混合方法：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 开发者门户以及最佳实践和示例

您如何遵循 API 优先/设计优先的方法？

要成功遵循这种混合方法，您必须确保您的公司将 API 置于其他产品之上，并且团队致力于协作来构建 API。

采用 API 优先和设计优先的方法进行 API 开发涉及以下步骤和实践，并行优先考虑规范和实现代码的设计、文档和迭代。

采用这种混合方法的一般准则如下。

确定需求

在编写规范之前，确保团队通过确定 API 需要支持的基本功能、数据结构和交互来了解 API 的要求。

定义API合约

选择符合这些要求的 API 架构和规范语言。接下来，指定数据模型、操作和身份验证机制，然后使用适当的工具创建和生成 API 规范，例如 OpenAPI、RAML 或 API 蓝图。

合作

API 优先方法需要业务利益相关者、开发人员和其他各方之间的密切合作，以维护 API 并维护 API 合同。

证实

经常验证 API 规范以确保其满足客户端应用程序的需求。

模拟和原型

只需一个规范，您就可以使用工具生成模拟响应来模拟“真实”API。前端开发人员甚至可以在 API 开发完成之前就开始使用虚假服务器响应构建客户端应用程序。原型设计提供了一个尽早捕获反馈以测试 API 设计可用性的机会。

实施

一旦规范经过验证并满足客户端应用程序的需求，开发团队就可以根据 API 规范实现 API 端点和业务逻辑。此外，框架和库允许您仅根据 API 规范生成样板代码，您可以使用它来实现 API。

测试

彻底的测试可确保 API 实现符合 API 规范并按预期运行。无需从头开始构建测试工具，而是利用维护良好的 API 测试框架和工具来验证规范以确保合规性。

记录并生成 SDK

如果您的 API 与 OpenAPI 等模式语言一致，您可以使用工具根据 API 规范生成文档。 API 参考文档至关重要，以便 API 用户了解资源、端点、请求/响应模式、身份验证和授权以及针对开发人员的任何其他指南，例如入门指南和操作教程。此外，根据 API，您可以根据 API 规范生成客户端 SDK 和代码示例，从而简化客户端应用程序的集成。

部署和版本

以下是部署 API 和版本控制的一些准则：