一个 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 就是一个 API-first 的优秀案例,设计和开发了一系列的 API 工具平台,包括 API 快速生产、研发管理、自动化测试、网关、监控、开放平台等,实现对 API 的全生命周期覆盖。首创提出 DTDD(文档与测试驱动开发 )理念,通过标准化的工具和流程来解决 API 迭代效率的问题,致力于让 API 管理更简单。
DTDD ( 文档与测试驱动开发 ):
文档驱动开发:项目开发前,先把文档写好,明确功能需求、入参出参定义、异常情况处理等,再进行开发。
测试驱动开发:项目开发前,先写好测试方案/用例,要求代码顺利通过测试,如不通过则持续进行改进。