常见问题

JSON API的版本是什么意思？

如今的JSON API是一个稳定的1.0版本，它会一直遵循“永不移除，只添加”的策略向后兼容。

版本主要是为了：

有几个原因：

HAL递归嵌入子文档，而JSON API在顶层扁平化对象结构，意味着同一“people”被不同对象引用（如，“posts”和“comment”的“author”）时，此格式能保证每个“person”文档仅存在一个有效实例。
类似的，JSON API 使用IDs作为连接，使得从复合响应中缓存文档成为可能，仅当本地不存在对应文档，才会发出后续请求。幸运的话，甚至可以完全无需HTTP请求。
HAL 是序列化格式，但完全未定义文档更新操作。JSON API 则仔细考虑如何更新已存在文档（依赖 PATCH 和 JSON PATCH），以及更新操作与GET请求返回的复合文档交互方式。同时定义如何创建，删除文档，以及更新操作的 200,204 响应。

简单来说，JSON API 尝试格式化相似的，特殊的client-server通讯接口，使用 JSON 作为数据交换格式。专注于使用成熟的客户端来调用相关API，客户端能够缓存已经获取到的文档，避免再次请求已缓存信息。

JSON API 从大量实际项目所使用的库中抽象而出。同时定义请求/响应（HAL 未定义），以及对应数据交互格式。

当一个客户端请求一个URI时，服务器端可以包含一个Allow header 在它的响应中，表明请求的资源支持该方法。服务器端希望支持方法发现应包含这个头。然后，为了发现它所支持的方法，客户端可以发送一个到URI的“HEAD”请求。

例如，客户端请求“HEAD/articles”，且响应包含”Alow:GET.POST”头，以表明客户端可以“GET”集合并“POST”到它，以生成新的资源。

JSON API仍以它们对于资源的宣传和细节的非标准操作支持方式工作。可以随时加入这个讨论!！

使用PUT来部分更新一个资源（例如，只改变一些它的状态），HTTP规范是不允许的。反之，PUT可以完全取代一个资源的状态。

“PUT方法请求以状态 生成或替换 目标资源……在一个请求的有效载荷内，给定的‘representation’ 的成功的‘PUT’表明随后有同一目标资源的‘GET’将导致发送一个等价的‘representation’……”

局部更新的正确方式是JSON API 所用的PATCH，因为PATCH可以使用全资源置换，目前，JSON API不必为PUT定义任何行为。然而，PUT语义可能在以后定义。

过去，许多API使用PUT来进行部分更新，因为PATCH不像如今支持得这么好。然而，如今几乎所有客户端都支持PATCH，包括那些以前不容易处理的。

当然，你可以在http://jsonapi.org/schema找到 JSON 规范的定义。这个规范尽可能做了限制的，不过在你的文档中可以灵活地扩展。验证不会产生漏报率，但为了灵活性却可以产生误报率。

可以在ttp://json-schema.org找到更多关于JSON 规范格式的信息。

JSON数组是自然排序，而集合需要元数据进行成员排序。因此，默认情况下，数组能够实现更自然的排序或者特殊方式排序。

主要资源应是分离开来的，因为他们的顺序和数字通常是比较重要的。有必要分离主要资源和关联资源为多种类型，因为主要资源和关联资源有可能有相同的类型（例如，一个“person”的“parents”）。将关联资源嵌入included对象中以避免这种可能的冲突。

JSON API 对于URI结构没有要求，他们可以自由的使用所希望的任何格式实现。