RESTful 处理子资源

Question

我一直在创建一个 RESTful 应用程序，但尚未决定如何处理不返回资源的所有实体或返回多个资源的请求（GET /resource/all 请求）。请允许我花一点时间来设置情况（我会尽量概括这一点，以便它可以适用于除我之外的其他人）：

假设我正在创建一个产品 API。为简单起见，假设它返回 JSON（在发送正确的接受标头之后）。可以通过/product/[id] 访问产品。产品有评论，可通过/products/[id]/review/[id] 访问。

我的第一个问题在于这个子资源模式。由于您在获取产品时可能并不总是想要评论，因此可以通过另一个 URI 访问它们。根据我的阅读，我应该包含请求的 URI，它将在产品请求的响应中返回产品的所有评论 URI。我应该怎么做才能遵守 RESTful 标准？它应该是像Reviews-URI: /product/123/review/all 这样的标头，还是应该像这样在响应正文中包含 URL：

{ 'name': 'Shamwow',
  'price': '$14.99',
  'reviews': '/product/123/review/all'
}

我的第二个问题是关于 /product/[id]/review/all 请求应该如何运行。我听说我应该只发送所有评论的 URL 并让用户获取每个评论，而不是将所有评论打包到一个请求中。我应该如何根据 RESTful 标准指示这组评论 URI？我应该使用标头还是在响应正文中列出 URI，如下所示：

{ 'reviews': [ '/product/123/review/1',
               '/product/123/review/2',
               '/product/123/review/3'
             ]
}

Answer 1

您的问题是您没有使用超媒体。超媒体特别具有链接到其他事物的元素。

您应该考虑HAL，因为这是一种超媒体内容类型，碰巧也在 JSON 中。

然后，您可以利用 HAL 中的链接为您的评论提供参考。

Answer 2

至于您的第一个问题（标题或正文），绝对不要发明您自己的自定义标题。这里有些人会争辩说你应该使用Link header，但我认为你会发现嵌套链接有很多需要并且应该将它们保留在正文中。

如何指示reviews/ 资源的 URI 或其中的 URI 列表完全取决于您选择代表每个资源的媒体类型。例如，如果您使用 HTML，则可以使用锚标记。如果您使用的是没有超媒体语法的纯 JSON，您将不得不花一些时间在 API 的文档中描述哪些值是 URI，或者通过使用特殊键指定它们，或者将它们包装在特殊语法中，例如 @ 987654324@，或带有相关架构文档。

查看Shoji，这是一种基于 JSON 的媒体类型，专为这种子资源模式而设计。

Answer 3

JSON Schema 标准可能对您有所帮助，尤其是 Hyper-Schemas。

它允许您定义如何从数据中提取链接 URI，以及它们的“rel”是什么 - 实质上是将您的 JSON 数据转换为超媒体。因此，对于您的第一个数据，您可能会编写如下架构：

{
    "title": "Product",
    "type": "object",
    "properties": {...},
    "links": [
        {"rel": "reviews", "href": "{reviews}"}
    ]
}

href 的值是URI Template - 例如，如果您的数据包含productId，那么您可以将href 的值替换为"/product/{productId}/review/all"。

对于第二个示例数据（评论列表），您可能有这样的架构：

{
    "type": "object",
    "properties": {
        "reviews": {
            "type": "array",
            "items": {
                "links": [
                    {"rel": "full", "href": "{$}"}
                ]
            }
        }
    }
}

在href的URI Template中，{$}的特殊值表示“JSON节点本身的值”。因此，Hyper-Schema 指定 reviews 数组中的每个项目都应替换为指定 URL (rel="full") 处的数据。