构建 API 的提示

现在，企业和组织比以往任何时候都更加依赖 API 来为其客户提供服务。另一方面，微服务架构和无服务器设计正变得越来越普遍。这就需要建立更多的 API 集成点，这将确保企业获得更多可见性，并使他们能够比其他竞争对手占据上风。

在本文中，我们将讨论一些技巧，这些技巧将帮助您构建一个能够满足客户所有需求的健全的 API。这些设计技巧将允许您快速有效地构建无错误的 API。

1. 对 API 进行版本控制：识别和理解您正在尝试构建的产品的概念非常重要。这有助于您预先定义需求，并允许您向利益相关者公开应用程序的行为和功能。从 API 开发过程开始，保持 API 版本控制以跟踪需求并允许 API 的平滑更改变得非常重要。

2. 使用 API 规范框架：它们有助于标准化跨组织的开发过程。他们拥有涵盖整个开发生命周期的工具，从产品的想法到最终的应用程序。这提供了更好的互操作性并允许您执行自动化。您可以使用 OpenAPI、Swagger 等工具。它们还允许您通过一个统一的平台生成文档、与 CI/CD 工具集成。

3. 为错误响应创建一个结构：您应该以这样一种方式设计您的 API，即您的所有方法都将以相同的格式和样式返回错误响应。如果某些错误返回错误的原始形式而没有任何非技术用户难以理解的信息，这看起来很奇怪。维护一个结构，使错误响应包含易于理解的信息。

4. 创建解释清楚的文档：虽然编写文档可能是一项无聊而繁重的任务，但它同样重要。它们可以分为两种类型。

5. 内部文档：包括代码风格、命名方法约定、请求、参数、响应等技术细节，主要为同一项目的其他开发人员设计。

6. 公共文档：主要是为将要使用你的 API 的用户设计的。在这里，您需要用简单易懂的语言描述如何使用 API、如何进行集成、如何解决错误等。

7. 为每个端点创建一个格式：使用标准格式在 API 中指定每个端点总是更好。例如，对于每个端点，您可以指定一个示例请求、关于所发生情况的简短描述、输入参数（如名称、类型、必需等）的描述、请求的示例响应以及每个端点的描述响应中的字段。您可以使用 Swagger 等工具，也可以手动编写它们。建议随时更新文档。

8. 保持路径和参数的标准样式：您需要事先决定如何命名您的 API 方法、参数和其他细节。遵循通用结构不是强制性的，但始终遵循相同的结构非常重要。

考虑下面的例子：

• GET https://myapi.sample.com/product/list – 获取所有产品的列表
• GET https://myapi.sample.com/productcodes – 获取所有产品的产品代码。

不推荐使用上面的示例，因为它对类似的请求使用不同的命名约定。例如，它使用单数词产品后跟列表来显示所有产品，而在第二个示例中，它使用复数词来显示所有产品代码。

9. 始终使用过滤和分页：为用户提供一种使用分页过滤结果的方法非常重要。对于返回商品列表的 API，如果您更改商品的顺序或商品本身，则很难过滤这些商品。因此，始终建议您建立分页策略来创建产品列表。

例如，

• 获取 https://myapi.sample.com/product?page=1
• 获取 https://myapi.sample.com/product?page=2
• 获取 https://myapi.sample.com/product?page=3

上述示例是维护产品列表或任何其他对象的良好做法。

10. 始终保护您的端点：遵循 CIA 安全三元组，即：机密性、完整性、可用性。您需要确保采用适当的身份验证控制，以便您作为管理员知道谁在尝试访问您的 API。您可以使用第三方身份验证提供程序，例如 OAuth2 和 JWT。需要通过添加授权和适当的访问控制来确保完整性，以便没有未经授权的用户可以篡改您的 API。最后，您应该使用速率限制器、缓存和其他类似工具来确保您的 API 始终可用，并且不会受到大量流量或无限循环的阻碍。

最后，在本文中，我们讨论了开发 API 时需要采取的一些重要措施。采用所有重要实践来创建、记录、调试和与最终用户共享 API 端点是非常重要的。