RESTful API 设计 - 使用资源 URI 与 ID

Posted 2023-02-19

【中文标题】RESTful API 设计 - 使用资源 URI 与 ID

【英文标题】：RESTful API design - using a resource URI vs an ID

【发布时间】：2021-09-30 10:02:04

【问题描述】：

这是我的第一篇文章，所以请多多包涵。

我正在设计一个新的 RESTful API，在我的客户如何与他们创建的资源交互方面我有两种设计选择。

例如，我有一个资源：“book”，它是一个简单的单例资源。

创建一本新书非常简单：

POST https://api.mydomain.com/book

我知道如果我希望操作是幂等的，我也可以使用 PUT。

此问题仅与 200 OK 响应选项有关，返回：

创建的“书”的匿名资源标识符 (UUID)：

book_id = 12345-67890

title = "一个奇妙的故事"

创建的“书”的完整 FQDN URI：

book_uri = "https://mylibrary.mydomain.com/upstairs/book/12345-67890

title = "一个奇妙的故事"

这当然会显着影响客户随后对“书”的操作。

要获得上述书籍的标题，客户端 API 调用可以是：

获取https://api.mydomain.com/book/book-id

示例：GET https://api.mydomain.com/book/12345-67890

注意：客户端将始终使用与 POST 调用相同的端点，只是简单地附加了 book-id。

获取 book-uri

示例：GET https://mylibrary.mydomain.com/upstairs/book/12345-67890

注意：客户端将直接从 POST 响应中使用 book-uri 对象变量。重要的是，返回的 book-uri) 可能与用于创建“书”的 POST 的 URI 完全不同。

所以我的问题（请）是：

Q1) 哪个模型更适合客户使用，为什么？

Q2) 您是否发现在大容量商业系统中使用选项 2 有任何问题？

提前感谢您的帮助和解答。

【参考方案1】：

您是否发现在大容量商业系统中使用选项 2 有任何问题？

因此，选项 2（其中 HTTP 响应包含新创建资源的 URI）是 Web 本身的工作方式，并且 Web 似乎作为一个大容量商业系统做得很好。

还请注意，选项 #2 允许服务器控制其 URI。例如，如果您稍后决定要修改资源模型，并为资源标识符使用不同的拼写，那么您可以这样做而无需对客户端进行任何更改。

例如，您还可以引入 URI 缩短组件，因为您再次获得了一个标识符，其中包含关于其工作方式的标准化规则。

您不一定需要使用完整的 URI - 我们还制定了关于如何使用 URI 片段在给定上下文中计算 URI 的标准化规则，因此您可能会有类似的选项

book_uri = "/upstairs/book/12345-67890",
title = "a fantastic story"

...取决于图书资源是否与处理 POST 请求的资源在同一主机上。

这样更好吗？这将取决于您需要做出哪些权衡，以及您对每个收益与成本的重视程度。

REST 接口旨在高效地进行大粒度超媒体数据传输，针对 Web 的常见情况进行了优化，但导致的接口对于其他形式的架构交互不是最佳的。 -- Fielding, 2000

【讨论】：

我认为选项2遵循“URI作为资源的唯一标识符”的原则。这也意味着其余的 api 应该符合 4 maturity models of REST apis 的第 3 级。对吗？