返回首页 用 JSON 构建 API 的标准指南
FAQ

用 JSON 构建 API 的标准指南

JSON API设计用来最小化请求的数量,以及客户端与服务器间传输的数据量。在高效实现的同时,无需牺牲可读性、灵活性和可发现性。

如果你和你的团队曾经争论过使用什么方式构建合理 JSON 响应格式, 那么 JSON API 就是你的 anti-bikeshedding 武器。

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

基于 JSON API 的客户端还能够充分利用缓存,以提升性能,有时甚至可以完全不需要网络请求。

下面是一个使用 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

下一篇: 介绍