建议

本节是JSON API实现的建议。这些建议是为了建立一致性，其描述的内容超出了JSON API规范的范围。

命名

成员的命名应该使用URL安全命名，其允许和推荐的字符被定义在格式规范中。同样是成员命名规范，推荐遵循下面的规则（更严格）。

成员命名应该以字符“a-z”（U+0061到U+007A）开始和结束。
成员命名应该只包含字符“a-z”（U+0061到U+007A），“0-9”（U+0030 to U+0039），和作为多个单词分隔符的连字符减号（U+002D HYPHEN-MINUS, “-”）。

URL设计

引用文档

在确定URL的结构时，假设所有的资源都在单个“引用文档”中，且每个资源都可以通过一个唯一的路径访问到。资源在文档的顶层被按照类型分组。在这些类型集合中使用ID来索引单个资源。单个资源中的属性和链接是访问上述资源对象结构的唯一方式。

引用文档的思想被用于确定资源的URL以及它们之间的关系。理解引用文档与用于传输的文档之间的不同是非常重要，他们的区别主要是目标与约束的不同。例如，引用文档中的集合表示为一个set，因为成员必须是可以通过ID访问的，而传输文档中会表示为一个array因为成员的顺序是有意义的。

资源集合的URL

建议根据资源类型来建立资源集合的URL。

例如，photos类型的资源集合URL应该像这样：

/photos

单个资源的URL

将资源集合视作set，并使用资源id来索引。单个资源的URL可以通过在集合的URL后添加资源ID来得到。

例如，ID为"1"的photo可以使用如下的URL表示：

/photos/1

关联URL和相关资源URL

就像基本规范描述的那样，每种关联都有两种URL表示方式：

“关联URL”——在relationship的links对象中使用self键来定义relationship自身的URL。这个URL允许客户端直接操纵该relationship。例如，这会允许客户端重post中移除author，但却不需要删除people资源本身。
“相关资源URL”——在relationship的links对象中使用related键来定义相关资源的URL。在获取后，该URL会将相关资源对象放在响应的主数据中返回。

建议在资源URL后追加/relationships/和关联的名称来得到“关联URL”。

例如，照片的comments关联的URL应该是这样：

/photos/1/relationships/comments

而照片的photographer关联的URL应该是这样：

/photos/1/relationships/photographer

建议在资源URL后追加关联的名称来得到“相关资源URL”。

例如，照片comments的URL应该是这样：

/photos/1/comments

而照片photographer的URL应该是这样：

/photos/1/photographer

因为这些URL表示的是关系中的资源，所以它们不应该使用self链接来表示它们本身。该建议对单个资源的self链接仍然适用。

过滤

基本规范没有对服务器的过滤策略作要求。filter查询参数被保留作过滤规则的基础。

例如，下面是一个获取指定post的所有评论的请求：

GET /comments?filter[post]=1 HTTP/1.1

多个过滤器的值可以使用逗号分隔符列表组合起来，例如：

GET /comments?filter[post]=1,2 HTTP/1.1

此外，一个请求中也可以使用多个过滤器。

GET /comments?filter[post]=1,2&filter[author]=12 HTTP/1.1

为缺乏`PATCH`的客户端提供支持

某些客户端，比如IE8，不支持PATCH方法。如果服务器希望支持这些客户端，那么建议将包含X-HTTP-Method-Override: PATCH标头的POST请求视为PATCH请求。这使得不支持PATCH的客户端可以简单地通过添加标头来升级现有的请求方法。

格式化日期和时间字段

尽管JSON API不对日期和时间字段的格式作要求，但建议服务器遵循ISO 8601规范。W3C的说明提供了对推荐格式的概述。

异步处理

考虑一种情况：你需要创建一个资源，该操作需要很长时间才能完成。

POST /photos HTTP/1.1

该请求应该返回202 Accepted状态，并将一个链接放在Content-Location标头中。

HTTP/1.1 202 Accepted
Content-Type: application/vnd.api+json
Content-Location: https://example.com/photos/queue-jobs/5234

{
  "data": {
    "type": "queue-jobs",
    "id": "5234",
    "attributes": {
      "status": "Pending request, waiting other process"
    },
    "links": {
      "self": "/photos/queue-jobs/5234"
    }
  }
}

为了检查工作进程的状态，客户端可以发送向之前给出的地址发生一个请求。

GET /photos/queue-jobs/5234 HTTP/1.1
Accept: application/vnd.api+json

当工作进程完成后，该请求应该返回303 See other状态，并将一个链接放在Location标头中。

HTTP/1.1 303 See other
Content-Type: application/vnd.api+json
Location: https://example.com/photos/4577

建议

命名