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

Question

这是我的第一篇文章，所以请耐心等待。

我正在设计一个新的 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}
示例：获取https://mylibrary.mydomain.com/upstairs/book/12345-67890

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

所以我的问题（请）是：

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

Q2) 您能看到在大容量商业系统中使用选项 2 的任何问题吗？

感谢您提前提供任何帮助和答案。

Answer 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 的常见情况进行优化，但导致接口对于其他形式的架构交互不是最佳的。 —— 菲尔丁，2000