让API设计清晰使用的7个技巧

每位开发者皆期望打造出直观且易于使用的API；同时，用户也期待着界面简单明了且易于操作的体验。庆幸的是，开发者们可运用一系列策略提升其API的质量。接下来，我们将分享七项实用技巧，助您轻松实现API设计的清晰与便利。

1. 保持一致

首先，开发 API 时需要保持一致。您针对 API 所做的一切都需要标准化和组织化，以确保尽可能保持一致。如果您的行动不一致，最终可能会得到设计不良的 API，无法按照您想要的方式运行。

例如，在命名项目时，您需要使用一种特定的逻辑来命名，而不是每次都以新的方式命名。从技术层面上讲，您还应该关注与 API 相关的文档，并确保其准确且一致。在与 API 相关的所有工作中，都要保持这种观点。

2. 简化命名

说到命名，简化项目的名称绝对是一个好主意。您需要以一种简单且不言自明的方式命名它们，这将帮助您避免混淆。避免混淆项目以及让您的团队在处理 API 时保持一致都很重要。

如果没有一些指导，每个开发人员都会独立决定使用什么命名约定，事情可能会变得一团糟。您最终可能会得到包含单个名词、复数名词和行话的接口。您还可能会得到包含不一致的大写字母和小写字母以及下划线和破折号的接口和属性。一旦开发人员在 API 中命名了事物，这些名称通常就不能轻易更改，因为这可能会对 API 使用者造成重大影响。在您的风格指南中包含一个概述命名约定的部分是非常值得的。

想象一下，当您的团队成员中有些人以一种方式命名物品，而其他人则以完全不同的方式命名物品时。沟通不畅和混乱是必然会发生的。这就是为什么您需要事先就命名系统达成一致，并使其尽可能简单明了。无需让事情复杂化。

3. 标准化响应和版本控制

除了就命名项目系统达成一致外，您还应该标准化错误响应，而不是尝试发明一些不需要发明的东西。大多数情况下，您需要做的就是查看类似 API 的现有示例，看看它们在不同情况下使用哪种错误消息。然后，您可以将相同的错误消息用于您自己的 API。

如果您使用版本控制，请在样式指南中包含指南，以便开发人员以相同的方式更新和弃用 API。您可以包含版本控制规则，例如：

始终对每个 API 应用版本编号，并解释编号方案。

切勿在 API URL 中包含版本号。

始终在 API 标头中包含版本号。

4. 严格指定

您可能已经注意到到目前为止列出的所有技巧的总体主题。简而言之，如果您想充分利用设计并确保您的用户像您一样喜欢它，您需要在使用 API 时井然有序。这正是您在指定 API 的不同方面时需要严格的原因。

例如，在设计接口、命名字段等时，您也应该具体。这将帮助您避免混淆，但在某些情况下，它实际上对于以正确的方式创建特定元素或项目至关重要。认真对待工作并严格指定所有内容。

在 API 样式指南中定义开发人员应遵循的单位、格式和标准。定义什么可能取决于您的行业，但“某些类型的数据（如日期时间）相对通用。”

5. 接受 API 密钥认证

除了考虑用户之外，您还应该考虑将来开发 API 并将其与其他应用程序集成的潜力。虽然您永远无法准确预测事情，但您可以肯定，接受API 密钥身份验证在未来肯定会有用。

为什么？因为它允许第三方与您的 API 进行集成。轻松的集成机会有助于采用和使用您的 API。

许多早期的 API 都使用了 API 密钥。虽然它们可能不是现在最新的安全标准，但它们通常比在 API 代码中传递其他凭据有所改进。API 密钥存在缺点，但它们也是确保访问安全的简单方法。

6. 利用分页

分页对于开发人员来说非常有价值，因为它允许您对返回资源集合的所有请求进行分页。在获取这些记录集合时，您还可以使用过滤和排序。

您的收藏会随着时间的推移而增长，因此您需要尽早开始限制和控制返回的元素数量。您还需要让用户对此有一定的控制权，但仍然需要预定义将显示的对象数量。

7. 尝试不同的技术手段

最后但并非最不重要的一点是，在开发 API 时，不要害怕尝试不同的技术技巧和窍门。您可能会遇到比实际实施的更多可以尝试的事情，因此最好有多种选择。以下是您在设计 API 时可以尝试的一些技术技巧：

提供健康检查接口。

使用合理的HTTP状态代码和方法。

在接口路径中使用名词。

提供扩展的响应选项。

使用 SSL 确保安全并配置 CORS。

总而言之，创建用户喜欢的良好 API 设计绝对是开发网站或应用程序的最重要方面之一。

本作品采用《CC 协议》，转载必须注明作者和本文链接