常见问题解答

JSON:API 版本的含义是什么？

现在 JSON:API 已经达到稳定的 1.0 版本，它将始终使用“永不删除，只添加”策略来保持向后兼容。

维护版本是为了

有几个原因

HAL 递归地嵌入子文档，而 JSON:API 将整个对象图展平成顶层。这意味着，如果从不同类型的对象（例如，帖子和评论的作者）引用了相同的“人员”，则此格式可确保有效负载中只存在每个人员文档的单个表示。
同样，JSON:API 使用 ID 进行链接，这使得可以从复合响应中缓存文档，然后将后续请求限制为仅获取本地尚不存在的文档。如果幸运的话，这甚至可以完全消除 HTTP 请求。
HAL 是一种序列化格式，但没有说明如何更新文档。JSON:API 考虑了如何更新现有记录（依赖于 PATCH 和 JSON Patch），以及这些更新如何与从 GET 请求返回的复合文档交互。它还描述了如何创建和删除文档，以及从这些更新中获得的 200 和 204 响应的含义。

简而言之，JSON:API 试图将类似的利用 JSON 作为交换格式的临时客户端-服务器接口形式化。它特别关注将这些 API 与知道如何缓存已看过的文档并避免再次请求它们的智能客户端一起使用。

它提取自一个由多个项目使用的真实世界库，该库已经告知了请求/响应方面（HAL 中没有）和交换格式本身。

每当客户端请求 URI 时，服务器都可以在其响应中包含一个Allow 标头，以指示请求的资源支持的方法。希望支持方法发现的服务器应包含此标头。然后，客户端可以发送一个HEAD 请求（或任何其他类型的请求）到 URI 以发现其支持的方法。

例如，客户端可能请求HEAD /articles，响应中可能包含标头Allow: GET,POST，表明客户端可以获取集合，也可以向其 POST 以创建新资源。

JSON:API 仍在研究资源宣传和详细说明它们支持的非标准操作的方法。欢迎你加入讨论！

使用 PUT 部分更新资源（即只改变其状态的一部分）是不允许的HTTP 规范。相反，PUT 应该完全替换资源的状态

“PUT 方法请求创建或替换目标资源的状态…在请求消息有效负载中。对给定表示的成功 PUT 将表明，对同一目标资源的后续 GET 将导致发送等效的表示…”

因此，部分更新的正确方法是PATCH，这是 JSON:API 使用的方法。并且由于 PATCH 也可以符合性地用于完全替换资源，因此 JSON:API 目前无需定义任何 PUT 行为。但是，它将来可能会定义 PUT 语义。

过去，许多 API 使用 PUT 进行部分更新，因为 PATCH 还没有得到很好的支持。但是，几乎所有客户端现在都支持 PATCH，而那些不支持的客户端可以轻松地解决。

是的，你可以在https://jsonapi.fullstack.org.cn/schema 找到 JSON Schema 定义。此模式尽可能严格，但在你的文档中具有扩展的灵活性。验证不会产生假阴性，但为了灵活起见可能会产生假阳性。

你可以在https://json-schema.fullstack.org.cn 找到有关 JSON Schema 格式的更多信息。

JSON 数组本质上是有序的，而集合需要元数据来指定成员之间的顺序。因此，数组默认情况下允许更自然的排序或按指定标准排序。

主资源应该被隔离，因为它们的顺序和数量通常很重要。有必要将主资源和相关资源区分开来，不仅仅是类型，因为主资源可能具有相同类型的相关资源（例如，“人”的“父母”）。将相关资源嵌套在 included 中可以防止这种可能的冲突。

JSON:API 对 URI 结构没有要求，实现可以自由使用任何形式。