清理 REST 中的 URI

Posted 2023-02-22

【中文标题】清理 REST 中的 URI

【英文标题】：Clean URIs in REST

【发布时间】：2016-01-30 20:29:09

【问题描述】：

我正在为客户设计一个新的 Web API。我之前没有设计过所谓的 RESTful API，而且我严重怀疑关于“做什么”和“不做什么”的炒作的有效性。

也许是我，但我不明白的一件事是为什么如此强调 URI 的结构。让 URI 代表资源，什么不是。

然后应用程序需要“预测” URI 包含的内容，其中包含大量有效代码和条件来处理不自然的 URL 结构。

几个世纪以来，我们一直在使用类似的东西：

get_all_products.php

还有：

get_product.php?id=1234

只要一切都有据可查，我无法理解为什么我们需要让应用程序变得更加复杂。

毕竟我们不是为搜索引擎创建 API！

【参考方案1】：

实际上大多数人完全误解了 Roy Thomas Fielding 最初提出的建议，很少有所谓的 RESTful 应用程序是真正 RESTful 的。

在他的博客文章REST APIs must be hypertext-driven 中，Roy 表达了他对人们将基于 HTTP 的接口称为 REST API 的失望，而事实上他们并非如此。

RESTful 应用程序的关键要素之一是：

除了初始 URI（书签）和适合目标受众的标准化媒体类型集（即任何可能使用 API 的客户端都可以理解）之外，应在没有任何先验知识的情况下输入 REST API。从那时起，所有应用程序状态转换必须由客户端选择服务器提供的选项来驱动，这些选项存在于接收到的表示中或用户对这些表示的操作暗示。转换可以由客户对媒体类型和资源通信机制的了解来确定（或限制），这两者都可以即时改进（例如，按需编码）。 （这里的失败意味着带外信息正在推动交互而不是超文本。）

这实际上是大多数正常网站的行为方式。

他在这里描述的是不是人们认为他们在应用程序中使用 URL 重写和所谓的单一入口点实现的，它与主题无关！

如果在初始 URI 之外不存在任何表示，并且服务器的响应没有提供进一步的链接，则实际上无法确定应用程序状态转换如何在该点之后继续进行。不管你如何构建你的 URI 以及你如何预测它，你都没有创建一个真正的 RESTful 应用程序。

使用类似的 URI：

https://www.example.com/api/1.0/products/

可以让客户端知道如果在“products/”部分之后输入“1234”，则获取特定产品。并且简化 POST、PUT 和 DELETE 方法，可以进一步使客户端能够确定可以在该特定资源上执行哪些操作，但它仍然不是一个真正的 RESTful 应用程序，因为除此之外，没有办法仅使用服务器提供的选择。

你真正拥有的是带外信息驱动交互而不是超文本，句号！

创建一个 HTTP 接口，确保使用清晰的复制/粘贴示例（无假设）记录所有内容，并且只需 KISS，不要跟随炒作！

【讨论】：

实际上，即使是像“example.com/api/1.0/products”这样的 URL，也不能让客户端知道比显示/获取的内容更进一步的信息。它可能是“1234”，也可能是“name”，也可能是“zip”或其他。无论如何都无法预测。