构建 API 的7个建议【翻译】

迄今为止，越来越多的企业依靠API来为客户提供服务，以确保竞争的优势和业务可见性。出现这个情况的原因是微服务和无服务器架构正变得越来越普遍，API作为其中的关键节点，继承和承载了更多业务。

在这个前提下，API 的设计需要考虑到哪些方面就尤为重要。在本文中，笔者将讨论有助于构建的 API 的7个建议（这些见解基于笔者为移动客户端构建 API 的经验，但可以更广泛地用于任何类型的API）。

| 将 API 视为产品

在开始任何类型的开发时，产品的概念都是最为关键的因素，产品是向用户展示有用的功能和好处的单独个体，这在 API 中也是一样。如果在开发过程中，没有强烈的责任感和主动意识，想要设计和完成一个易于使用、可扩展、正确记录和安全的 API 并非易事。

所以需要将 API 视为一个整体来看，从第一天开始就做好生产准备。因此，需要指派产品负责人将理想 API 的愿景传达给敏捷团队。开发人员和测试人员必须制定计划以使用最佳 API 实践，并避免常见错误。

| 使用 API 规范框架

通常，API 框架由涵盖从概念到生产的整个开发生命周期的工具库组成。虽然在开发 API 时遵守 OpenAPI/Swagger 之类的规范有点死板，但它提供了更好的工具规范性。能够在每次代码更改时生成文档、SDK 和 UI 交互点非常有用的，毕竟每个人都喜欢自动化。

如果关心标准并希望在描述的 API 时提供常规工具，那么国外的 Swagger、国内的 Eolink 都是非常可靠的选择，可以提前获得回报。

| 使用版本控制策略

API 会随着业务需求的变化而不断发展。作为产品，它会有一个特定的版本，因此客户会希望得到这个版本的正确响应。在客户不知道的情况下引入重大更改，更新已发布和使用的 API 接口就像定时炸弹一样，很容易出现问题，特别是当用户的手机上可能仍然安装了旧版本时。

有多种方法可以在 API 上强制执行版本控制信息，其中大多数 API 开发者选择将版本信息放在 URL 中，这确实很实用。例如，以下 URL 表示客户的资源端点：

及时更新适合业务的版本策略非常重要。不过，如果决定更新版本，提供警告、更新和其他机制会更让版本更新的影响更小。

| 使用过滤和分页

开发 API 时的一个常见错误是没有提供过滤或对结果分页的方法。当公开一个返回可随时间更改的项目列表的 API 时，我们需要建立分页策略。

原因很简单，客户端尤其是移动客户端，无法一次查看数百个列表项，通常只能显示前10个。如果 API 为每个请求返回整个数据库列表，那么会有大量资源被浪费并且性能显着下降。

现代框架提供了一种对结果进行分页的方法：对查询使用 LIMIT 和 OFFSET 语句。例如，通过下面的 MySQL 语句，返回总结果的一部分代码：

上面的语句将从数据库中检索第 6-16 行，所以还需要提供一个JSON响应，根据LIMIT参数给出指向该查询的第一页、下一页、上一页和最后一页的链接。

| 使用 REST 和 HATEOAS

REST 是一种经过验证和实践测试的设计 Web 服务的架构方法，它独立于任何底层协议。因此，它非常适合设计 API。通过使用 REST 原则，我们可以应用一些设计注意事项，例如：

将端点视为具有传统命名方案的资源。例如，如果要公开排序列表，可以公开以下端点：

如果想查找特定的排序，可以提供一个 ID 参数：

这种方法有几个优点，包括更好的一致性、可读性和连贯性。

• 促进无状态连接。这有助于使服务更具可扩展性，因为它们不会有在客户端和服务器通信之间保持状态的硬耦合约束。

• 在 HATEOAS 的帮助下，无需事先了解内部 URI 方案，即可在整个资源集中更轻松地导航。它通过提供一组相关链接来增强每个资源的响应模型，以便更轻松地与 API 交互，而无需查找规范或其他元数据服务。HATEOAS 的一种很好的格式是 HAL 规范。例如，这里是对特定文本资源的 HAL 响应，为记者公开相关链接：

| 保护端点

安全问题这是一定不能忽视的点。任何漏洞都可能导致严重的后果，甚至涉及法律问题。安全管控需要在开发过程的早期建立，理想情况下，API 需要由外部供应商进行评估。C.I.A 安全三原则（机密性、完整性和可用性）适用于以下情况：

机密性是通过添加适当的身份验证控制来实现的，这些控制为系统提供了一种方法来了解谁正在访问信息或站点。OAuth2 和 JWT 提供了一种实用且安全的方法控制身份验证。必须在所有公共端点使用 HTTPS 以确保安全通信。

完整性是通过使用访问控制和授权策略来防止未经授权的用户篡改数据来实现的。 基于角色的授权 是一个不错的选择。

可用性是通过建立速率限制、部分响应和缓存来实现的，以防止大量使用 API 资源甚至服务器被无限循环关闭。

| 使用监控和报告

虽然开发和测试 API 在这个过程中扮演着重要的角色，但真正的工作并没有就此结束。我们需要继续提供监控，甚至从代码部署到生产之后都要继续保持。如果出现问题，需要使用可操作的信息通知正确的人，以便通过任何必要的方式做出响应。这构成了开发 API 时的一种主动方法：监控与报告。只要保持谨慎，当端点问题出现时，我们就可以及时处理，防止任何灾难性故障。像 Eolink 也有这样的 API 监控工具，也可以帮助我们解决这个问题。

图中所使用的的接口管理工具是eolink，可以对不同类型的接口进行测试，在测试流程中也支持添加不同步骤，感兴趣可以自行使用：www.eolink.com