REST API URI 设计的 7 条规则

在讨论 REST API URI 设计规则之前，先快速概述一些相关术语。

URI 概述

REST API 使用统一资源标识符 (URI) 来寻址资源。当前的 URI 设计范围从清晰表达 API 资源模型的优秀案例，到一些难以理解的设计。

Tim Berners-Lee 在其“Web 架构公理”中提到，URI 应被视为不透明的标识符：“唯一可以使用标识符的，就是引用一个对象。当不取消引用时，不应查看 URI 字符串的内容以获取其他信息。”因此，客户端应遵循 Web 的链接范式，将 URI 视为不透明的标识符。

REST API 的设计者应创建能够向潜在客户端开发者传达资源模型的 URI。本文将介绍一组 REST API URI 的设计规则，并探讨如何使用 Keycloak 或客户端证书来保护 REST API 的安全。

在深入规则之前，首先介绍 URI 格式，因为本节讨论的规则与 URI 格式密切相关。根据 RFC 3986，通用 URI 语法如下：

URI = 方案“://”权限“/”路径[“?”查询][“#”片段]

规则 #1

URI 中不应包含尾部正斜杠 (/)。

这是必须遵循的最重要规则之一。作为 URI 路径中的最后一个字符，正斜杠 (/) 并不会添加任何语义，反而可能引起混淆。REST API 不应期望存在尾部斜杠，也不应在提供给客户端的链接中包含它们。

许多 Web 组件和框架将以下两个 URI 视为相同：

http://api.canvas.com/shapes/
http://api.canvas.com/shapes

然而，URI 中的每个字符都影响资源的唯一标识。

这意味着两个不同的 URI 实际上映射到两个不同的资源。如果 URI 不同，则资源也必然不同。因此，REST API 必须生成和传达干净的 URI，并不容忍客户端以不精确的方式识别资源。

较宽容的 API 可能会将客户端重定向到不带尾部斜杠的 URI，并可能返回 301 状态码（“永久移动”），以重新定位资源。

规则 #2

必须使用正斜杠分隔符 (/) 来指示层次关系。

正斜杠 (/) 在 URI 的路径部分中用于表示资源之间的层次关系。例如： http://api.canvas.com/shapes/polygons/quadrilaterals/squares

规则 #3

应使用连字符 (-) 来提高 URI 的可读性。

为了使 URI 易于扫描和理解，应在较长路径段中使用连字符 (-)。在英语中，任何需要空格或连字符的地方，都应在 URI 中使用连字符。例如：http://api.example.com/blogs/guy-levin/posts/this-is-my-first-post

规则 #4

URI 中不应使用下划线 (_)。

许多文本查看器（如浏览器和编辑器）会在 URI 上加下划线以提供可点击的视觉提示。根据不同应用程序的字体，下划线 (_) 可能会被遮盖或隐藏。

为避免这种混淆，应该使用连字符 (-) 代替下划线。

规则 #5

URI 路径中应优先使用小写字母。

尽可能在 URI 路径中使用小写字母，因为大写字母有时会引发问题。虽然 RFC 3986 定义 URI 为区分大小写，但方案和主机组件除外。

例如：

http://api.example.com/my-folder/my-doc
HTTP://API.EXAMPLE.COM/my-folder/my-doc

上面的 URI 被视为相同，而：

http://api.example.com/My-Folder/my-doc

则与前两个 URI 不同，这可能导致不必要的混淆。

规则 #6

文件扩展名不应包含在 URI 中。

在 Web 上，句点 (.) 通常用于分隔 URI 的文件名和扩展名部分。REST API 不应在 URI 中使用人工文件扩展名来指示消息实体主体的格式，而应依赖通过 Content-Type 头传达的媒体类型来确定如何处理正文内容。

例如：

http://api.college.com/students/3248234/courses/2005/fall.json
http://api.college.com/students/3248234/courses/2005/fall

文件扩展名不应用于指示格式首选项。

应鼓励 REST API 客户端使用 HTTP 提供的格式选择机制，即 Accept 请求头。

为了实现简洁的链接和便于调试，REST API 可以通过查询参数支持媒体类型选择。

规则 #7

端点名称应该是单数还是复数？

这里的简单规则是，尽量保持一致性。尽管语法上可能认为用复数描述单个实例是错误的，但实际上，始终使用复数可以使 URI 格式更加统一。

这样可以避免处理一些不规则的复数形式（如人/人，鹅/鹅），让 API 消费者使用起来更为便捷，同时也使 API 提供者的实现更为简单（因为大多数现代框架会自动处理如 /students 和 /students/3248234 的通用控制器）。

那么如何处理关系呢？如果关系仅能存在于另一个资源中，RESTful 原则提供了有益的指导。举个例子，一个学生可以选修多门课程，这些课程逻辑上可以映射到 /students 端点，如下所示：

http://api.college.com/students/3248234/courses – 检索 ID 为 3248234 的学生所学的所有课程列表。
http://api.college.com/students/3248234/courses/physicals – 检索 ID 为 3248234 的学生的物理课程。

结论

在设计 REST API 服务时，关注资源至关重要，这些资源通过 URI 来定义。

每个服务中的每一项资源都应至少有一个 URI 来标识它。这个 URI 应该具备意义，并能够充分描述资源。URI 应遵循可预测的分层结构，以提升可理解性和可用性：可预测意味着一致性，分层则指数据之间的结构关系。

RESTful API 是为消费者而编写的，因此 URI 的名称和结构应该向这些消费者传达清晰的含义。通过遵循上述规则，可以创建更加干净的 REST API，从而提高客户满意度。这不是单纯的 REST 规则或约束，而是对 API 的有效增强。

设计时应以客户为中心，而非仅仅关注数据。

原文链接：7 Rules for REST API URI Design