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 的资源模型传达给潜在的客户端开发人员。在这篇文章中，我将尝试介绍一组 REST API URI 的设计规则。了解如何使用 Keycloak 保护 REST API 的安全，或如何使用客户端证书保护 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 定义为区分大小写，但方案和主机组件除外。

例如：1）http://api.example.com/my-folder/my-doc

2) HTTP://API.EXAMPLE.COM/my-folder/my-doc

上面的 URI 就可以了。URI 格式规范 (RFC 3986) 认为此 URI 与 URI #1 相同。

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

此 URI 与 URI 1 和 2 不同，这可能会导致不必要的混淆。

规则6

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

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

http://api.college.com/students/3248234/courses/2005/fall.jsonhttp://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。

为您的客户设计，而不是为您的数据设计。

---

作者：Guy Levin

更多技术干货请关注公号【云原生数据库】

squids.cn，云数据库RDS，迁移工具DBMotion，云备份DBTwin等数据库生态工具。