设计API前，先建模你的API：API建模指南

经常有人问我，API的哪种风格更好：REST、GraphQL还是gRPC？我的回答通常是：“我不确定，你的API模型是怎么说的？”很多时候，我会遇到茫然的表情，或者听到一些关于数据库的回答。然而，我真正想问的是：“你的API解决了什么问题？为什么？”通过对API进行建模，我们可以更好地理解需求，从而选择最适合的API交互风格。

什么是API建模？

API建模是从多个角度定义API需要提供的功能的过程。它是一个迭代的过程，涉及到与API相关的人员，他们需要完成的任务，以及实现这些任务的步骤。通过API建模，我们可以更清晰地了解API的目标和用途。

API建模的类型

API建模需要根据具体业务背景进行调整。例如，REST API的资源建模方式与GraphQL API的建模方式会有所不同。然而，无论使用何种风格，建模过程中遵循的基本步骤是一致的。

需要注意的是，这里讨论的API建模是指定义API本身的过程，而不是利用API来辅助其他建模任务。例如，API财务建模是为财务建模提供支持的工具，而API主题建模则是为主题建模提供帮助的工具。

为什么在设计API之前需要建模？

直接从数据库开始设计API可能会导致API质量不佳，无法满足所有用户的需求。相反，我们需要从用户的角度出发，考虑API需要支持的功能以及用户的使用方式。

例如，在一个项目管理应用中，数据库可能存储了所有重要数据，但它并不能直接反映用户的需求。如果仅仅从数据库设计出发，我们可能会设计出一个CRUD风格的HTTP API，但这样的API往往过于关注数据库表，而忽略了用户的实际需求。

API建模可以帮助我们在设计API之前，建立更好的沟通实践。通过建模，我们可以明确API存在的原因，以及它计划解决的问题。

API建模的五个步骤

第1步：确定API的用户

首先，需要明确谁会使用API。这些用户可以是开发者、运营工程师、最终用户，甚至是其他应用程序和设备。了解不同用户的需求是建模的第一步。

例如，在一个项目管理应用中，我们可以将用户分为以下几类：

项目经理：负责创建和监督项目。
开发人员：与API直接交互。
系统管理员：管理系统配置。

明确用户角色不仅有助于API建模，还能为后续的文档编写提供支持。

第2步：确定预期结果

用户并不关心API的内部实现，他们关心的是API能实现哪些功能。例如，对于一个项目管理API，用户可能希望能够从头到尾管理项目。

这些预期结果可能需要多个步骤来实现。在下一步中，我们将进一步分解这些步骤。

第3步：绘制步骤图

每个预期结果都由一系列步骤组成，每个步骤由API的一个或多个端点支持。通过分解步骤，我们可以更深入地了解API如何解决实际问题。

例如，在项目管理API中，管理项目的步骤可能包括：

创建新项目。
添加项目成员。
更新项目状态。

第4步：定义API模型

在明确了所有步骤后，我们可以开始定义API模型。这包括确定API的资源和操作。此时，我们的目标是创建一个粗略的草图，以验证API需求。

例如，对于项目管理API，我们可能会定义以下资源和操作：

用户帐户
项目成员
项目问题

这些资源和操作为后续的API设计提供了基础。

第5步：验证API模型

最后一步是验证API模型是否满足需求。通过线框图、用户故事和测试用例，我们可以确保API能够满足所有用户的需求。

在验证过程中，需要特别注意以下几点：

是否遗漏了某些用户角色或功能？
是否有需要依赖其他API的地方？
是否有可能成为高频使用的端点？

API建模的最佳实践

以下是一些API建模的最佳实践，帮助你更高效地完成建模工作：

明确API的目标和需求

花时间明确API的目标和用户需求，这对成功的建模至关重要。

使用标准化的数据格式和协议

采用OpenAPI规范（OAS）或OpenTelemetry等标准，可以提高API的易用性和集成效率。

注重命名的沟通性

资源的命名应该清晰易懂，方便所有用户理解。

早期引入主题专家

在定义步骤和结果时，主题专家的参与可以提供宝贵的见解。

不要忽视验证阶段

验证阶段是确保API模型符合需求的关键。不要急于跳过验证，直接进入设计和开发。

总结：为API设计做好准备

通过API建模，我们可以更清晰地了解API需要支持的功能和实现这些功能的步骤。在此基础上，我们可以选择最适合的API设计风格。

例如，对于项目管理API，我们可能会选择基于资源的方法，并应用REST约束。在这种情况下，可以将步骤映射到具体的API端点。

从建模到设计的过渡需要结合HTTP原则和API风格，最终形成完整的API设计。

原文链接: https://tyk.io/blog/before-you-design-your-api-model-your-api/