掌握良好的 API 设计原则：是什么、为什么和怎么办

API 设计原则是数字世界中建立强大连接的模型，其中 API 弥补了系统之间的差距。本文简化了 API 设计的复杂性，向您介绍了确保功能性、可靠性和易用性的经过验证的原则。学习如何奠定优秀 API 的基础，而无需猜测，这样您就可以专注于真正重要的事情：打造一款能够无缝集成并根据技术需求扩展的卓越工具。

关键要点

• 有效的 API 安全性包括采用 JWT 等身份验证协议、TLS 等加密标准以及处理敏感数据的保护措施（包括 HTTPS）、避免敏感 URL 数据以及加密日志和缓存。

• 良好的 API 设计需要直观且可预测的端点结构，具有清晰的资源命名约定、使用标准 HTTP 方法进行 CRUD 操作以及嵌套资源的结构良好的层次结构，以方便使用和可扩展。

• 全面的文档对于成功采用 API 至关重要。它应包括详细的 API 契约，由 Swagger 和 Postman 等工具支持测试和发现，并通过变更日志和更新让用户了解情况。

制定安全的 REST API

在 REST API 和 Web 服务领域，我们面临着重要的安全任务。网络威胁无处不在，因此 REST API 的安全至关重要。目标是通过采用强大的身份验证和授权程序，仅授权用户执行操作。

SSL/TLS 协议的实施为我们的 (API) 通信提供了安全的通道。此外，监控和记录 API 活动可充当警卫，识别和预防潜在威胁。

身份验证协议

问题出现了——我们如何才能只向合法用户授予堡垒访问权限？基于令牌的身份验证协议提供了解决方案。这些协议就像只有授权用户才知道的秘密握手。其中，JSON Web 令牌 (JWT) 脱颖而出，成为一种流行的选择，它充当验证用户身份和保护堡垒（API 端点）访问的护照。

然而，这些护照的有效期很短，从而降低了未经授权访问的风险窗口。因此，JWT 和其短暂性相结合，形成了对入侵力量的强大防御。

加密标准

然后，我们探讨加密，这是我们安全工具包中的一个关键策略。传输层安全性 (TLS) 加密客户端和服务器之间的数据传输，从而保护 API 通信。

API 网关充当一道保护盾，提供 TLS 或相互 TLS (mTLS) 等功能，这对于实现加密至关重要。这些加密标准类似于一种只有用户才能理解的神秘语言，可确保信息的安全交换并阻止任何拦截其通信的企图。

处理敏感数据

为保证敏感信息的安全传输，应采取以下措施：

• 使用 HTTPS 在传输过程中加密数据

• 避免在 URL 中包含敏感数据，以防止泄露

• 加密服务器日志和缓存以保护敏感信息

• 设置缓存控制标头来管理敏感信息的缓存

通过实施这些措施，您可以有效地保护敏感数据并确保 API 中的安全访问数据。

堡垒的网关充当着强大的保护层，在可疑请求到达 API 之前将其过滤掉。同时，Web 应用程序防火墙 (WAF) 可防范 DDoS 攻击和其他恶意流量。通过实施这些措施，我们确保我们的珍宝——敏感数据——得到妥善保护。

设计直观的端点和路径

结构良好的 API 架构注重设计的技术方面，从而打造高效、安全且用户友好的环境。这包括清晰的标识（资源命名）、简单的路由（HTTP 方法）和结构良好的层次结构（嵌套资源）。

资源命名约定

为了提供用户友好的 API，请对资源集合使用复数形式（例如 /users），对单个资源使用单数名词（例如 /users/123）。这可使 API 直观且更易于理解。

清晰的 API 导航：命名规则

• 集合：复数：对资源组使用复数（例如，/products）。

• 子集合：层次结构：命名子集合以显示其在主集合中的位置（例如，/products/categories）。

• 可读性：用连字符分隔单词（例如，/order-details）。

这可确保您的 API 具有清晰的“标志”，从而方便用户使用。

HTTP 方法和操作

标准 HTTP 方法对于在 RESTful API 中执行 CRUD 操作至关重要，类似于明确定义的程序指导操作的方式。这些方法是：

• 创建（POST）：创建一个新的资源。

• 读取（GET）：检索资源或资源集合。

• 更新（PUT/PATCH）：更新资源（PUT 替换整个资源，PATCH 更新特定部分）。

• 删除（DELETE）：删除资源。

在设计端点 URI 时，应使用反映实体的清晰的名词路径，并且 HTTP 方法（而不是 URI）定义对资源的操作。将 HTTP 方法与其预期的 CRUD 操作对齐有助于为消费者提供直观且可预测的 API 交互。

构建嵌套资源

在我们的应用程序中，有许多部分，每个部分都有不同的角色。同样，在 API 设计中，嵌套或相关资源必须具有结构化的层次结构，以促进协作并最大限度地减少深度级别。嵌套资源应使用反映其与单独资源的关系的分层 URI 来寻址，从而实现直观的数据访问和操作。

然而，在设计嵌套资源时，必须避免 URL 过长、端点冗余和不必要的数据库查询，因为这些会使 API 复杂化并降低效率。应谨慎使用嵌套资源，以保持高效、可扩展且易于使用的 API。因此，结构良好的堡垒可让用户高效移动和协作。

有效的响应管理

有效的响应管理包括使用标准 HTTP 状态代码、制作信息响应主体以及实施速率限制以确保适当的 API 通信。

利用 HTTP 状态代码

此请求的结果可以通过一个简单的标志系统来传达。同样，HTTP 状态代码充当这些标志，在服务器和客户端之间传达 HTTP 请求（例如 API 请求）的结果。

不同的代码表示不同的状态 – 操作成功、错误或需要采取其他措施。遵守标准 HTTP 状态代码并避免使用自定义代码是一种最佳实践，类似于遵循通用标志代码，可防止沟通错误。

HTTP 状态代码使客户端无需检查响应主体即可了解其请求的结果，从而立即清楚了解状态代码和请求的结果。

制作信息丰富的响应主体

在 API 世界中，响应主体就像是一份附有标志的详细报告。在 API 响应的请求主体中包含请求的数据和相关元数据可以提高清晰度并提供关键上下文或附加信息。这就像用户不仅知道他的请求被拒绝，还知道为什么被拒绝。

“X-Request-Id”响应标头通过跟踪服务器上的整个请求生命周期来帮助调试特定请求。用户可以全面了解自己的请求，从发出请求到做出决定，这有助于理解和改进未来的请求。

实施速率限制

为了防止滥用和维持秩序，任何城堡都会限制请求或授予的观众数量。同样，在 API 设计中，速率限制对于防止系统滥用和保持服务器性能至关重要。

实现速率限制的各种技术包括节流、请求队列和基于算法的方法，如固定窗口、漏桶、滑动日志和滑动窗口。另一种策略是负载削减，即在系统接近过载时拒绝 API 请求以确保稳定性。

API 通过响应标头将速率限制和服务器状态传达给客户端，指导用户相应地调整其请求模式。因此，速率限制就像守门人一样，确保堡垒的平稳运行。

促进客户端与服务器之间的数据交换

我们现在专注于应用程序内的信息交换。客户端请求或用户与服务器之间的高效数据交换对于优化 REST API 中的客户端-服务器数据交换至关重要。这涉及使用高效的数据序列化格式、内容协商和压缩技术。

数据格式和交换

在任何对话中，使用的语言都是至关重要的。在 API 设计中，选择合适的数据格式（如 JSON）以实现兼容性和性能，就如同使用一种通用、高效的语言。JSON 数据采用键值对结构，而 XML 数据采用分层树模式表示，JSON 的简单性使其更适合 API。了解 API 设计中使用的正确数据结构对于有效沟通至关重要。

JSON 文件通常文件大小较小且更易于解析，从而加快数据传输速度并提高 API 性能。另一方面，XML 支持更多样化的数据类型，在数据表示方面提供更大的灵活性。因此，选择正确的数据格式就像选择应用程序内最有效的通信语言一样。

内容协商

客户端和服务器可能需要以各种格式交换数据。这时内容协商就派上用场了，让它们能够就传输数据和要共享的文档格式进行沟通。

客户端使用“Accept”标头来指定它们理解的媒体类型格式，而“Content-Type”标头则指示发送回客户端的数据的媒体类型。在请求期间，客户端可以向服务器端发送一个“Accept”标头，其中包含“application/json”或“application/xml”等值，以指示其偏好，而服务器则使用“Content-Type”标头进行响应，以指定发送的数据的格式。这类似于用户和服务器就对话的通用语言达成一致。

压缩技术

gzip 和 brotli 等压缩技术可以传递简洁的信息，节省带宽并提高网络传输速度。

客户端可以使用 HTTP 标头（例如“Accept-Encoding”）来指定它们支持的压缩方法，服务器可以使用“Content-Encoding”来指示所提供内容的压缩方法。实施这些技术可以通过加速数据传输和减少延迟来显著提高 API 性能。

高级查询功能

配备高级功能的工具包始终具有优势。在 API 领域，高级查询功能如下：

• 过滤

• 排序

• 搜索

• 字段选择

通过监控和优化 API 行为来增强 API 功能。

过滤和排序

假设一名抄写员根据特定标准对卷轴进行排序。API 世界中的过滤和排序工作方式类似。高效的做法会限制返回的无效数据量，从而优化性能并节省服务器资源，尤其是在处理大型数据集时。

限制/偏移分页使用“限制”参数来定义要返回的项目数，并使用“偏移”参数来指定起点，使其在 API 中易于实现。高级过滤机制利用带有键值对的 URL 参数和运算符（例如“gte”和“lte”）来表示范围过滤器。

搜索和字段选择

就像高级搜索选项可以简化用户查找所需信息的流程一样，API 也受益于强大的搜索功能。这些功能允许过滤和选择特定的数据字段，从而高效地检索所需的内容。API 可以通过支持复杂查询来增强其搜索功能，从而启用范围搜索、术语匹配和模糊匹配等操作来优化搜索结果。

为了扩展搜索功能，API 可以利用 Lucene 或 ElasticSearch 等高级搜索技术启发的语法，在搜索参数中实现过滤器和范围。这就像骑士使用高级搜索技术来找到他需要的准确卷轴一样。

长效的版本控制策略

API 也会随着时间的推移而发展。版本控制是 REST API 设计软件开发不可或缺的一部分，可确保支持旧 API，同时系统地发布更新和新功能。它能够以受控的方式引入新功能、纠正错误并弃用过时的功能。

API 版本控制方法

选择合适的版本控制方法类似于规划城堡的扩建。URI 版本控制涉及将版本号直接包含在端点 URL 中，这使得实现变得简单，但会导致 URL 更长。查询字符串参数版本控制将版本号放在 URL 的查询参数中，从而产生更清晰的 URL。

标头版本控制将版本信息引入 HTTP 标头，从而保持干净的 URL 并节省 URI 空间，但可能会增加客户端请求的复杂性。媒体类型版本控制将版本数据嵌入 HTTP 标头中的媒体类型声明中，从而实现对版本的精细控制。选择正确的版本控制方法就像为应用程序的扩展选择最有效的设计一样。

传达弃用信息

在 API 设计中，弃用涉及逐步淘汰 API 功能，向 API 消费者传达这些即将发生的变化非常重要。

提前宣布变更并提供明确的时间表可确保用户充分了解新功能和弃用的功能。将用户过渡到新版本需要提供清晰的文档和支持以促进更新过程。因此，良好的沟通时间表可确保堡垒的居民能够顺利适应变化。

综合文档：您的 API 蓝图

全面的 API 设计文档与产品构建和维护蓝图一样重要。文档充当 API 的蓝图，为有效的 API 使用和采用提供基本信息。

编写清晰的 API 契约

API 契约类似于服务器和 API 之间的协议，描述了双方的期望。编写良好的 API 契约的特点是简单、一致，并且有详尽的文档，涵盖输入、输出、错误代码和用例示例。

开放 API 规范等开发工具可以帮助确保传入的数据符合预期的数据类型和属性，在符合 API 契约的输入验证中发挥关键作用。通过遵循 API 设计原则，将 API 契约测试自动化作为持续集成过程的一部分，可以保持对定义的契约行为的遵守。

因此，清晰的 API 合同可确保每个人都知道自己的角色和职责。

API 文档工具

绘制 API 蓝图需要一套适当的工具。在 API 设计领域，Swagger 和 Postman 等工具对于编写详尽的文档和测试 API 至关重要。

Swagger 和 Postman 直接连接到文档，大大提高了 API 使用者的可发现性。这就像拥有不仅能帮助绘制蓝图而且能让堡垒的所有居民轻松访问的工具。

变更日志和更新

API 的变更都有记录，就像城堡翻新的更新一样。使用发行说明和变更日志来传达 API 变更可确保用户充分了解新功能和弃用的功能。

维护变更日志对于通知用户更新（尤其是重大变更）以及确保其实现的持续功能至关重要。这就像在堡垒中记录所有变更，帮助堡垒中的居民适应这些变更。

概括

我们在 API 设计堡垒中的历程涵盖了众多领域 – 从保护 REST API、设计直观的端点、管理响应和促进数据交换，到引入高级查询功能、版本控制策略和全面的文档。掌握这些原则是创建强大、高效且用户友好的 API 的艺术的证明。

原文链接：Mastering Good API Design Principles: The What, Why, and How