术语表

要点速览（TL;DR）：

• HTTP 请求是针对 JSON:API 的资源（resources）发起的。不要将它们与资源对象（resource objects）混淆。
• 客户端接收的 JSON 对象称为文档（a document）。
• 文档始终是一个 JSON 对象，并且在 data 键下包含主数据（primary data）。
• 该键下的数据称为资源对象（resource objects）或资源标识符对象（resource identifier objects）。
• 当你请求将相关数据内嵌到文档中时，它就成为复合文档（compound document）。
• 复合文档是在顶层对象中包含 included 键的文档。
• 返回多个资源对象的资源称为集合资源（collection resources）。
• 返回单个资源对象的资源称为单体资源（individual resources）。
• 返回关于资源对象之间关系信息的资源称为关系资源（relationship resources）。
• 在 Drupal 术语中：
  • Resource Objects → Entities（实体）
  • Resource Identifier Objects → 实体引用字段条目（Entity reference field Items）
  • Document → 请求/响应的 JSON 载荷（payload）

下面是描述 JSON:API 模块时所用术语与概念的简要说明。

本术语表与 JSON:API 规范非常接近，但尝试以适用于 Drupal 的方式来阐释定义。它还扩展了规范中的一些细微之处，以便那些不熟悉规范或不了解如何阅读规范的新手也能理解。

这些定义中的许多彼此交织。有一张页面底部的图表，将这些术语放在它们出现的上下文中进行说明。

资源（Resource）

一个可以检索 JSON:API 响应文档的位置。资源可以通过其 URL（统一资源定位符）找到。它不应与“资源对象”混淆。资源与应用程序的数据并不是一一对应的。

在 Drupal 术语中，JSON:API 的资源并不等同于一个实体。相反，资源是你可以检索某个概念数据的地方。例如，这个概念可以是“node--article 类型的资源对象集合”，也可以是“某篇文章节点上 field_tags 实体引用字段的表示”。

响应文档（Response Document）

从 JSON:API 资源返回的 JSON 编码响应主体（body）。它是将数据或错误传达给 HTTP 客户端的“信封”。有时也称为顶层对象（top-level object）。当文档包含一个 included 的文档成员时，它被称为复合文档（compound document）。

复合文档（Compound Document）

包含 included 文档成员的响应文档。复合文档可以通过内嵌相关的资源对象，将其置于响应文档的主数据旁，从而减少 HTTP 请求。可以通过在请求 URL 中添加 include 查询参数来请求复合文档。

错误文档（Error Document）

包含 errors 文档成员的响应文档，其中含有一个或多个错误对象（error objects）。它永远不会包含 data 文档成员。包含错误文档的响应的 HTTP 状态码总是 4xx 或 5xx 级别。

单体资源（Individual Resource）

其 响应文档的 data 成员中包含单个资源对象的资源。在权限足够时，此资源可读且可变更。以 Drupal 而言，此资源可用于“查看（view）”、“更新（update）”或“删除（delete）”单个实体。它不能用于“创建（create）”实体。

集合资源（Collection Resource）

其 响应文档的 data 成员中包含多个资源对象的资源。在权限足够时，此资源可读且可写。这类资源可以被分页、筛选和排序。在 Drupal 中，此资源可用于“创建（create）”新实体，但不能用于“更新（update）”或“删除（delete）”集合中的实体。

关系资源（Relationship Resource）

其 响应文档的顶层对象是一个关系对象（relationship object）的资源。它包含一个或多个资源标识符对象，每一个都表示从某个资源对象指向另一个资源对象的引用。在权限足够时，此资源可读且可变更。以 Drupal 而言，此资源可用于“查看（view）”或“编辑（edit）”某个实体引用字段的条目。

相关资源（Related Resource）

一种特殊的集合资源，其 响应文档的 data 成员包含一个或多个资源对象。该集合中的资源对象是某个引用方资源对象上某个关系的目标。此资源为只读。以 Drupal 而言，此资源可用于“查看”由某个实体引用字段所引用的实体，但不能用于“更新”这些实体或“编辑”引用它们的实体引用字段。

文档成员（Document member）

顶层 JSON:API 文档的一部分（一个 JSON 对象）。这些对象总是位于规范定义的键下（例如 jsonapi、data、included 或 errors）。

资源对象（Resource Object）

以 JSON 对象表示的一个实体。它不应与“资源（resource）”混淆。资源对象与应用程序的数据是一一对应的。

属性对象（Attributes Object）

一个 JSON 对象，表示其所在的资源对象的信息。属性可以包含任何合法的 JSON 值。在 Drupal 术语中，该对象表示所有非实体引用的实体字段值。

关系对象（复数，Relationships Object）

一个 JSON 对象，包含其所在的资源对象到其他资源对象的引用。它包含多个成员，每个成员都是一个“关系（单数）对象”。在 Drupal 术语中，该对象表示所有实体引用字段的值。

关系对象（单数，Relationship Object）

一个 JSON 对象，表示其所在的资源对象到其他资源对象的引用。它包含资源标识符对象，每个都表示到另一个资源对象的一条关系。在 Drupal 术语中，该对象表示单个实体引用字段。

资源标识符对象（Resource Identifier Object）

一个非常简单的 JSON 对象，表示从一个资源对象到另一个资源对象的关系。它不应与“资源对象”混淆。它仅包含 type 与 id 键，以及可选的 meta 键，用于承载关于该关系的信息。值得注意的是，它不包含 links 成员。

它提供“资源链接（resource linkage）”，在复合文档中，使 HTTP 客户端可以将关系对象与 included 成员中的被引用资源对象进行关联。

链接对象（Links Object）

一个 JSON 对象，包含到其他资源的超链接。

错误对象（Error Object）

一个 JSON 对象，表示在处理请求时发生的错误。这些错误可以表示客户端错误、校验错误、服务器错误等。

Artical from Drupal Documentation.