一个 API-First 设计应该具有可复用性、互操作性、可修改性、用户友好性、安全性、高效性、务实性，并且重要的是，与组织目标保持一致。这些基本特征将确保 API 能够有效地为 API- First 组织战略和开发模式做出贡献，在这种模式中，API 可以最大限度地为业务创造价值。

但如何生成这样的 API-First 设计呢？

在本文中，我们将探讨如何通过以下五个流程集成到 API 设计过程中来实现 API-First 设计：

• 使用自然语言来分析和应对需求
• 观察上下文并确定约束条件
• 充分描述和记录 API
• 利用现有的 API 和指南
• 将自动化和人工反馈循环集成到流程中

1. 使用自然语言来分析和应对需求

为了确保创建的 API 符合组织的目标，需要使用自然语言深入分析需求。这种分析可能涉及明确消费者或最终用户、他们的用例以及如何实现它们，这对于确定满足需求所必需的每个 API 功能至关重要。进行分析后，应与利益相关者交流预期，以确保一致性。

在进行此类分析时，只能使用自然语言，不考虑编程接口表示，通过这样区分问题将有助于与专家讨论，并避免过早地就诸如/customers or /customer或PUT or POST之类的问题展开辩论。最终，你可能会意识到有比标准 REST API 更好的选择，例如，gRPC、异步或 GraphQL API 可能更适合。

2. 观察上下文并确定约束条件

API 设计者和利益相关者必须观察 API 上下文，并确定所有约束条件以确保 API 设计实用、高效且安全。这可能涉及到以下问题：

• 新 API 应该在什么时候部署？

• 底层系统是否存在限制？

• 主题内容是否符合我们创建 API 的常用方法？

• 安全要求是什么？

接下来，API 设计者和利益相关者可以决定是隐藏还是将约束条件融入设计中。隐藏它们可能会带来额外的工作，但设计更好。另一方面，将它们纳入其中可能会降低 API 的质量，但更容易按期交付。然而，请务必记住安全性是一个不可妥协的问题。

3. 全面描述和编写 API 文档

在设计过程中写好 API 文档至关重要，以确保捕获所有信息，如编程接口描述、需求及其分析、约束和安全要求。这也可以指导你创建合适的 API。

为了描述和记录 API，你可以轻松地使用诸如 OpenAPI、AsyncAPI、GraphQL schema 或 JSON Schema 等 API 规范。这些规范将为你提供一个框架，但它们只能用于记录 API 的元素，而不是消费者如何组合它们以实现在需求分析期间确定的用例。

无论你使用哪种格式，把需求分析和生成 API 连接起来至关重要，以确保最终设计中不会遗漏任何内容。同时还需要向实施者提供尽可能多的信息，确保实现符合预期，例如，在 OpenAPI 文档中， 你可以通过查看摘要来确认在需求分析过程中确定“搜索客户”的操作已转换成 GET /customers 。此外，还可以查看操作安全配置及响应描述，以确保仅返回用户或消费者范围内的客户。

4. 利用现有 API 和指南简化决策过程

API 设计过程涉及到大量的决策。然而许多决策是相同的，因为所有的 API 最终都要处理相同的基本问题，例如，表示日期或金额的最佳方式、如何搜索目录、创建资源或启动流程等。此外，在一个组织内部，所有 API 必须具有共同的样式。

为了避免在漫长且重复性高的讨论中浪费时间或重新设计轮子，可以参考组织内其他 API 并复制它们的设计模式。不过，在描述常见“配方”，如“如何设计搜索操作”或者“如何管理文件上传”的指南中，更高效的方法是将这些模式形式化。API 指南可以涵盖各种主题， 从用户友好性到安全性， 但它们只作用于促进创建 API-First 设计。如果某个指导原则规定对实现该目标没有帮助，就删除它。

遵循指南能够快速实现具有一定用户友好性、互操作性、可扩展能力、安全性和效率的 API 设计，但最重要的是可以帮助你专注于核心问题，创建正确的 API，而不会浪费时间和精力在遣词造句问题上。

5. 将反馈循环整合到流程中

即使指南涵盖了所有相关主题，并以友好的方式呈现，但总有一些 API 设计者可能永远不会看，其他相关的人可能会通过反复检查指南中的细节而减缓进程。此外，任何人在编程接口设计中都可能犯一些小错误。因此，尽早寻求同事、专家和消费者的迭代反馈至关重要，与他们共享扩展的 API 文档以及模拟数据，确保他们能获取到所需的信息，以提供建设性的有效反馈。

Eolink 翻译，原文《How to enhance your API-first design process》