JSON API实体是否应包含其父级的关系？

Question

我一直无法找到明确的答案，希望有人可以提供帮助。

如果我们有一个带帖子的博客，每个帖子都可以有评论，每个评论都是相关用户。如果我请求评论，是否违反惯例，在关系中包括用户和帖子？

data: {
  type: 'comments',
  id: '1',
  relationships: {
    post: {...}, //should this be here?
    user: {...},
  }
  attributes: {...},
},
included: {...}

Answer 1

正如paulsm4正确地说：“这取决于你”。

但我可以给你一些建议。

在这种情况下，你可以通过查询字符串标志给API的调用者选择是否有这样的链接，比如

?relationships=post,user

在这种情况下，如果您没有指定关系标志，您将获得简单的评论数据，或者您可以决定全部给出它们;在第二种情况下，您可以将关系用作一种过滤器。

在一些API中，我也看到了一种更具侵入性的方法：将相关对象直接嵌入到返回的JSON中。

使用与以前相同的技术：

?embed=post,user

这应该在当前JSON回复中生成一个嵌入的JSON对象，包括原始对象，就像你分别询问“GET / post / 123”或“GET / user / 456”这样的东西。在某些情况下，这可能很方便。

这个标志通常被命名为“expand”，表示相同或相似的行为。

举个例子，打开this API documentation from Atlassian并搜索“expand”。

它确实存在一个旧的“标准”，你的问题叫HAL，它讲的是在REST API中链接和嵌入。

即使Wordpress API提供了这样的功能，也可以在official documentation中查看。

另一种方法是使用REST方法在GraphQL中重写整个API。

Answer 2

问：JSON API实体是否应包含其父级的关系？

答：我认为这完全取决于你！

如果你的JSON是由某个第三方定义的，那么你必须忍受他们给你的东西。请发布有关如何指定JSON的详细信息。

否则，如果你自己“发明”这种格式：

1. 一种可能性是让relationships:字段带有“父母”的链接。
2. 也许更好的解决方案可能是发明一个“容器”（也许是一个简单的数组！）来保存你的“记录”。
3. 如果这是一个数据库，我会有一个“posts”表和一个“comments”表。 “comments”表将“Post ID”列作为“posts”表中的外键。

'希望有帮助......至少有点......

Answer 3

JSON API规范不对资源对象中包含的属性和关系提出任何要求。规范只是说如果包含它们必须如何格式化它们。如果我没有遗漏任何内容，规范甚至不要求所有相同类型的资源对象必须具有相同的属性和关系。

但我认为不包括关系没有任何价值。 JSON API规范不要求relationship object包含resource linkage数据。相反，它只讨论compound document上下文中的资源链接数据，其中它用于“将所有包含的资源对象链接在一起，而不必通过链接获取任何URL”。

它是完全有效的，如果相关资源不包含在有效载荷中，则可以被认为是仅提供related resource link的最佳实践。构建此类链接不会在您的服务器上放置任何工作负载，因为它不需要查询数据库。它也没有使有效载荷大小产生任何相关差异。

使用这两种技术的有效载荷的示例将如下所示。它假定请求明确要求使用include query param包含相关用户。

// GET https://examples.com/api/v1/comments/1?include=user

{
  data: {
    type: 'comments',
    id: '1',
    relationships: {
      post: {
        links: {
          related: 'https://examples.com/api/v1/comments/1/post'
        }
      },
      user: {
        data: {
          type: 'users',
          id: '2'
        },
        links: {
          related: 'https://examples.com/api/v1/comments/1/user'
        }
      },
    }
  },
  included: [
    {
      type: 'users',
      id: '2',
      attributes: {
        name: 'John Doe'
      }
    }
  ]
}

您可能还想要包含一个relationship link，它“允许客户直接操纵关系”。规范的Update relationships chapter深入探讨了使用关系链接可以实现的目标。