JSON:API — 使用 JSON 构建 API 的规范

如果您曾经与团队就 JSON 响应的格式问题争论不休，那么 JSON:API 可以帮助您停止无谓的争论，专注于真正重要的内容：您的应用程序。

通过遵循共享约定，您可以提高生产力，利用通用工具和最佳实践。围绕 JSON:API 构建的客户端能够利用其功能，高效地缓存响应，有时甚至完全消除网络请求。

以下是一个实现 JSON:API 的博客的响应示例

{
  "links": {
    "self": "http://example.com/articles",
    "next": "http://example.com/articles?page[offset]=2",
    "last": "http://example.com/articles?page[offset]=10"
  },
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "links": {
          "self": "http://example.com/articles/1/relationships/author",
          "related": "http://example.com/articles/1/author"
        },
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "links": {
          "self": "http://example.com/articles/1/relationships/comments",
          "related": "http://example.com/articles/1/comments"
        },
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    },
    "links": {
      "self": "http://example.com/articles/1"
    }
  }],
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "firstName": "Dan",
      "lastName": "Gebhardt",
      "twitter": "dgeb"
    },
    "links": {
      "self": "http://example.com/people/9"
    }
  }, {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "First!"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "2" }
      }
    },
    "links": {
      "self": "http://example.com/comments/5"
    }
  }, {
    "type": "comments",
    "id": "12",
    "attributes": {
      "body": "I like XML better"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    },
    "links": {
      "self": "http://example.com/comments/12"
    }
  }]
}

上面的响应包含了一个“文章”集合中的第一个元素，以及指向该集合中后续成员的链接。它还包含与文章链接的资源，包括其作者和评论。最后，还提供了用于获取或更新这些资源的链接。

JSON:API 不仅涵盖响应，还涵盖创建和更新资源。

MIME 类型

JSON:API 已在 IANA 正式注册。其媒体类型标识符是 application/vnd.api+json.

格式文档

要开始使用 JSON:API，请查看基本规范的文档。

扩展

JSON:API 社区创建了一系列扩展，API 可以使用这些扩展为客户端提供超出基本 JSON:API 规范中描述的信息或功能。这些扩展被称为配置文件。

您可以浏览现有的配置文件，或者创建一个新的配置文件。

里程碑

该规范的主要里程碑包括

2022-09-30：1.1 正式版发布。
2015-05-29：1.0 正式版发布。
2013-07-21：媒体类型注册在 IANA 完成。
2013-05-03：草案初版发布。

更详细的历史记录可在此处获得此处。

您可以订阅单个更改的 RSS 订阅源此处。