链接与嵌入

WP REST API 在整个 API 中融入了超链接，以支持资源的可发现性和可浏览性，同时还能将相关资源嵌入到单个响应中。虽然 REST API 并未完全遵循整个 HAL 标准，但它实现了该标准中的 ._links 和 ._embedded 属性，如下所述。

链接

响应对象的 _links 属性包含一个指向其他 API 资源的链接映射，按“关系”（relation）分组。该关系指定了链接资源与主资源之间的关联方式。

示例包括：
– author – 描述资源与其作者之间的关系
– wp:term – 描述帖子与其标签或分类之间的关系

关系类型可以是：
– 标准化关系
– URI 关系 – 例如 https://api.w.org/term
– 或 Compact URI 关系 – 例如 wp:term

如果需要，Compact URI 关系可以规范化为完整的 URI 关系以确保完全兼容。这类似于 HTML 的 <link> 标签或 <a rel=""> 链接。

这些链接是一个对象，其中包含一个带有资源绝对 URL 的 href 属性，以及其他可选属性。这些属性包括内容类型、消歧信息以及与该链接相关的可执行操作数据。

对于集合响应（即返回对象列表而非顶层对象的响应），每个项都包含链接，而顶层响应则通过 Link 头来包含链接。

如果您的客户端库不允许访问头信息，可以使用 _envelope 参数将头信息作为正文数据包含在内。

示例响应

典型的单篇帖子请求 (/wp/v2/posts/42)：

{
  "id": 42,
  "_links": {
    "collection": [
      {
        "href": "https://example.com/wp-json/wp/v2/posts"
      }
    ],
    "author": [
      {
        "href": "https://example.com/wp-json/wp/v2/users/1",
        "embeddable": true
      }
    ]
  }
}

嵌入

可选地，一些链接资源可以被包含在响应中，以减少所需的 HTTP 请求数量。这些资源会被“嵌入”到主响应中。

嵌入是通过在请求上设置 _embed 查询参数 来触发的。这将把嵌入的资源包含在 _links 键旁边的 _embedded 键下。此对象的结构与 _links 对象镜像对应，但用嵌入的资源替换了链接属性。

只有设置了 embeddable 标志为 true 的链接才能被嵌入，且 _embed 会导致所有可嵌入的链接都被嵌入。然而，_embedded 中仅包含包含嵌入响应的关系；对于混合了可嵌入和不可嵌入链接的关系，将为不可嵌入的链接提供虚拟响应，以确保数字索引与 _links 中的保持一致。

当嵌入集合响应时，例如 /wp/v2/posts?author=1，嵌入的集合将应用默认的分页限制。

示例响应

{
  "id": 42,
  "_links": {
    "collection": [
      {
        "href": "https://example.com/wp-json/wp/v2/posts"
      }
    ],
    "author": [
      {
        "href": "https://example.com/wp-json/wp/v2/users/1",
        "embeddable": true
      }
    ]
  },
  "_embedded": {
    "author": {
      "id": 1,
      "name": "admin",
      "description": "Site administrator"
    }
  }
}