JSON API：用 JSON 构建 API 的标准指南中文版

译文地址：https://github.com/justjavac/json-api-zh_CN

假设你和你的团队以前争论过使用什么方式构建合理 JSON 响应格式， 那么 JSON API 就是你的 anti-bikeshedding 武器。

通过遵循共同的约定。能够提高开发效率。利用更普遍的工具。能够是你更加专注于开发重点：你的程序。

基于 JSON API 的client还可以充分利用缓存，以提升性能，有时甚至可以全然不须要网络请求。

以下是一个使用 JSON API 发送响应（response）的演示样例：

{
  "links": {
    "posts.author": {
      "href": "http://example.com/people/{posts.author}",
      "type": "people"
    },
    "posts.comments": {
      "href": "http://example.com/comments/{posts.comments}",
      "type": "comments"
    }
  },
  "posts": [{
    "id": "1",
    "title": "Rails is Omakase",
    "links": {
      "author": "9",
      "comments": [ "5", "12", "17", "20" ]
    }
  }]
}

顶级的 "links" 部分是可选的。

除去 "links" 部分，此响应看起来很接近使用已经存在的 API 构建的响应。

JSON API 不仅能够用来构建响应，还包含创建和更新资源。

现状

本文档是一个正在进展的工作。在具体实现过程中将会有所改变。具体信息请查看现状页面。

MIME 类型

JSON API 已经在 IANA 机构完毕注冊。 它的 MIME 类型是 application/vnd.api+json。

格式

在開始使用 JSON API 前。先查看一下JSON API 格式文档

更新历史

• 2013-05-03：最初版本号的草案。
• 2013-07-22：媒体类型在 IANA 注冊完毕。

你能够使用 RSS 阅读器在这里订阅本提要的变更。