API 开发的最佳实践

API 是一套规则，定义了应用程序或设备的用户友好性。它是一个软件中介，使应用程序之间可以互动。它可以是基于网络的系统、数据库系统等。像 Netflix、Facebook 和 Github 这样的科技巨头在这方面处于领导地位。他们雇佣 API 开发人员利用 API 处理其应用程序的数据，并为用户提供最佳可能的体验。

然而，API 开发并非易事。它需要大量的努力、奉献和精心规划。由于缺乏有效管理 API 的方法，许多公司无法高效地处理这项任务。有一些最佳实践是开发人员应始终遵循的。在这里，我列出了一些最佳的 API 开发实践，将帮助有效地维护和使用 API。

1. API 应遵守所在国家和行业法律规范

各个国家和行业的法律法规都有所不同，你的 API 开发团队必须确保你的业务遵守目标国家/行业的规定。如果你的 API 不符合相关法规，那么你可能会因为创建了一个有缺陷的应用程序而支付高额罚款或面临监禁。例如，医疗领域的 API 需要遵守诸如 HIPAA（美国）或 IEC 62304（国际）等法规。请确保了解这些法规，并使你的 API 符合这些要求。

Eolink「API 全生命周期协作管理平台」是业内率先通过了 ISO27001「信息安全管理体系认证」和 ISO9001「质量管理体系认证标准」两项国际权威认证的企业，为用户提供业内更加安全可靠的产品和服务。

2. 减少调用次数以降低延迟

API 用于在软件服务、设备等之间传输数据，减少调用次数可以降低延迟，从而带来更好的用户体验。例如，如果你的 API 列出了用户，请使用所有必要的数据作为参数调用“getAll”。如果正确执行，将最大限度地减少网络调用。

3. 集成越多，效果越好

将你的 API 与其他第三方技术/API 集成，以便在需要时它们可以协同工作。这将使你的 API 能够做更多事情，并帮助你创建一个更强大的平台。你可以为项目雇佣 API 开发人员。

例如，通过开源库或企业服务总线（如 Apache Camel、MuleSoft 等）进行集成，可实现轻松集成并缩短上市时间。

4. API 应满足消费者的需求

API 旨在为消费者服务，而不是为你自己服务。确保你的 API 具有足够的灵活性，以便在必要时进行未来更改。此外，最好确保你的 API 可以毫无困难地与其他技术/API 集成。

当你决定更改数据库结构或实施新型技术时，请勿担心破坏兼容性并改进 API。例如你的 API 从数据库中检索数据。如果你允许消费者查询数据库，请允许他们使用标准查询子句，如“where”。

5. 确保 API 具备可扩展性

请务必制定一个周全的负载均衡和扩展计划，以防止在太多消费者同时访问你的 API 时出现宕机。这是 API 开发人员常见的问题，因为他们没有考虑到如何应对来自外部资源的访问。

例如，假设你的 API 为消费者提供数据，所以你允许他们查询数据库。但是你无法知道有多少外部资源会同时请求你的 API。最好实施一些负载均衡技术/方法，以防止在突然受到大量外部资源攻击时 API 宕机。

6. API 必须安全

在大多数行业中，安全性是首要任务，API 也应遵循相同的概念。最佳做法是对用户进行身份验证和授权，以便他们只能访问允许访问的内容，并对通过互联网传输的任何数据进行加密。

API 在传输数据时确保了最高的安全性，它会将你的 API 密钥以及 API 使用者所需的任何其他数据进行加密并安全存储。这样，在所有集成中都能够实现安全传输。例如，假设你有一个消费者应用程序，需要通过你的 API 向消费者提供一些数据。该应用程序需要一个加密过的 API 密钥，以便在调用你的 API 时对其进行解密。

7. 确保版本管理简单

版本控制是在保持向后兼容性的同时为 API 添加新功能。API 版本控制与其他类型的软件类似；应该保持简单，以便消费者在使用特定版本时不会感到困惑或迷失。它还适用于不同的数据类型，如果没有正确实现，可能会导致混乱。在定义每个版本应使用哪种数据时，请考虑消费者体验。

例如，第 2 版和第 3 版将具有不同的数据类型，因此消费者需要在使用之前了解这一点。这是一个基本示例，但表明了在开发 API 时考虑消费者有多重要。

8. API 文档至关重要

文档可能是所有 API 最关键的部分。这需要记录每个方法、参数、输入和输出，以便开发人员了解你的 API 如何工作。在编写时，最好使用机器可读格式而不是人类可读格式，因为这将使程序/软件更容易集成。

例如，在记录一个方法时，你应该使用机器可读格式而不是人类可读格式，因为软件可以更好地解释它。

9. 设计高性能和高可用性 API

在创建 API 时，你应该尽可能提高其性能，通常通过减少请求数量来实现。同时，你还需要确保它们具有很高的可用性，这可以通过使它们分布式且容错来实现。当设计面向大流量或使用率的 API 时，这两个因素都非常重要。

假设你的 API 性能不佳，并且消费者在短时间内多次调用它。如果你考虑到性能和高可用性而设计了 API，则应避免此类情况发生。否则会导致 API 停止运行，从而给消费者带来糟糕的体验。

10. API 必须使用行业标准

在设计 API 时，遵循行业标准是最佳选择。你可以使用当前最流行的标准，如 RESTful API、JSON、XML 等。这些是大多数开发者熟悉的标准，因此消费者更容易使用你的 API。

假设你设计了另一种不太流行或广泛使用的 API 使用标准。由于较少人知道如何使用它们，所以缺乏相关文档，并且消费者可能会感到沮丧，因为他们不知道如何操作这些 API。采用行业标准意味着文档和其他资料将广泛可用，使得消费者能够轻松地使用它们。

11. 保持服务边界明确

服务边界定义了一个服务可以被使用或访问的范围。这确保了你的 API 设计具有可重用性和模块化。一个恰当的类比是，如果你在制造汽车——你不会创建一个拥有相同零件的大型车辆，因为这样效率会降低。相反，你会设计各种不同但可以一起使用的小型车辆。

消费者需要知道什么是服务边界以便正确地与它们配合工作。如果没有将两个不同的服务区分开来，则必须同时完成它们才能正常运行。假设你有两个 API，一个用于驾驶，另一个用于转向。

12. SEO 始终至关重要

搜索引擎优化（SEO）对于任何网站或 API 排名都至关重要。这不仅仅是拥有一个好产品 - SEO 对于传播信息并让消费者了解你的 API 非常必要。确保你的文档进行了 SEO 优化，以便通过搜索引擎更容易地获得排名。

例如，如果你在未优化 SEO 的情况下过多地更改文档设计，那么消费者将很难找到它们，从而降低使用它们的可能性。保持 SEO 优化以获得更好的排名，并向外界传播有关 API 的信息。

13. API 设计应该用户友好

API 设计应该用户友好且直观，如果消费者无法自行了解 API 的工作原理，他们可能会感到沮丧并停止使用它们。这将导致你的 API 采用率降低，使得传播有关它们的信息变得更加困难 —— 保持文档和实际设计对用户友好可以增加消费者使用它们的机会。

如果你的 API 不直观，消费者需要花费更多时间学习它们是如何工作的，而不是尝试一下看看是否适合他们所需。因此，在短时间内消费者需要判断一个 API 是否具有功能性以便他们不浪费时间。

总结

总的来说，API 应该具备高可用性、性能优越、遵循标准、明确的服务边界、SEO、用户友好设计以及可重用性。遵循这些最佳实践将确保 API 满足业务需求和消费者需求，从而提高采纳率。

Eolink 翻译，文章《API Development Best Practices to Follow in 2022》，作者：Ajay Kapoor