我应该如何在目录端点中指示 hatoas 链接？

Question

我们正在尝试在一些 API 中开始使用 HATEOAS，但我们对如何在响应中编写链接有一些疑问。所以我们有这个端点，它返回资源列表。我们对

rel

中使用的名称有一些疑问。我们对团队有两种看法：

1. 每个资源里面的

   rel

   应该被称为

   self

   。

{
  "items": [
    { "id": 1, "_links": { "rel": "self", "href": "host/resources/1"} },
    { "id": 2, "_links": { "rel": "self", "href": "host/resources/2"} },
    ...
  ],
  "_links": { "rel": "self", "href": "host/resources"}
}

2. 每个资源里面的

   rel

   应该被称为

   details

   。

{
  "items": [
    { "id": 1, "_links": { "rel": "details", "href": "host/resources/1"} },
    { "id": 2, "_links": { "rel": "details", "href": "host/resources/2"} },
    ...
  ],
  "_links": { "rel": "self", "href": "host/resources"}
}

选项二背后的推理是

self

表示您用于获取该响应的相同 URL，从技术上讲，它必须是

host/resources

。另一方面，选择选项 1 的人建议使用

self

必须指向端点才能获取

_links

属性所在的对象。

也许我们只是把这个问题复杂化了，不确定。您认为正确的做法是什么？是否有关于常见 HATEOAS 命名/结构的标准？

Answer 1

“self”关系的当前注册的参考是RFC 4287。

值“self”表示 href 属性值中的 IRI 标识与包含元素等效的资源。

以 Web Linking 的形式表达，“self”表示链接目标是链接上下文的首选 URI。 （期望是，如果未指定显式上下文，则有一些规则用于如何确定隐式上下文 - 就网络而言，这通常意味着上下文是您正在查看的网页）。

具有与用于获取资源的标识符不匹配的自我目标是很好，但不一定常见。

---

“详细信息”似乎是一个错误 - 截至 2023 年 4 月 6 日，没有详细信息关系的 [注册参考]。 这意味着您正在处理“扩展关系”，并且您可能不希望在这种情况下使用隐式引用解析；扩展关系由 URI 标识，因此您应该使其看起来像一个 { "rel": "https://example.org/link-relations/details", "href": "host/resources/2"}

注意：扩展关系类型应该是 URI (RFC 3986)，但不一定必须是 

HTTP

URI。

您可能还需要考虑您（通常）被允许指定针对单个 URI 的

---

多个关系类型

的含义。 Link </B>; rel="self https://example.org/link-relations/details"

因此，如果您认为细节意味着与自我不同的东西，并且您想向客户传达这两种关系，您可以这样做（这样做的具体细节取决于您的表示的产生规则）。