任何命名的 link 都可以进入 JSON:API "links" 对象，还是我们只能得到 "self" 和 "related"？

Question

我正在寻找有关构建可发现 API 的示例或指导，其中将包含 link 索引路径（“/”）响应主体中的资源。 JSON:API 文档说“可能”包含“自身”和“相关”link。相关文档：

The value of each links member MUST be an object (a “links object”)

但是它没有明确说每个link成员的键可以是任何东西，它不是'不要明确说明只允许“自我”和“相关”成员。但是，我没有看到任何 link 成员命名为其他名称的示例。(?)

这是有效的 JSON:API 回复吗？

{"links": 
  "self": "/",
  "widgets": "/api/widgets"
}

Answer 1

链接在 JSON:API 规范中可能有不同的上下文，具体取决于它们在 JSON:API 文档中出现的位置。这在即将发布的规范 v1.1 中表达得更清楚：

A link’s context is the top-level object, resource object, or relationship object in which it appears.

https://jsonapi.org/format/1.1/#document-links

我假设您是在询问顶级 link 的允许成员。顶级 link 是 JSON:API 文档的 link。

允许的顶级 link 受规范限制：

The top-level links object MAY contain the following members:

self: the link that generated the current response document.

related: a related resource link when the primary data represents a resource relationship.

pagination links for the primary data.

https://jsonapi.org/format/#document-top-level

即将推出的 v1.1 引入了 describedby 顶级 link:

describedby: a link to a description document (e.g. OpenAPI or JSON Schema) for the current document.

其他成员可以在即将发布的 v1.1 中通过 extension 指定。扩展可以“通过定义额外的规范语义来扩展基本规范”。这包括为对象定义其他成员：

An extension MAY define new members within the document structure defined by this specification.

规范定义的成员必须命名空间：

When an extension defines new [...] document members, the extension MUST define a namespace to guarantee that extensions will never conflict with current or future versions of this specification.

这样的命名空间是一个字符串。它作为使用冒号 : 作为分隔符的前缀应用于规范定义的所有成员。

通过使用扩展，您可以将任何成员添加到 links 对象。

任何命名的 link 都可以进入 JSON:API "links" 对象，还是我们只能得到 "self" 和 "related"？

can any named link go into the JSON:API "links" object or do we only get "self" and "related"?

json-api