JSON:API 是什么？

JSON:API 是一种用于构建 JSON 接口的规范。它不是新的数据格式，而是规定 API 响应应该如何组织 JSON：资源、关系、链接、错误、字段选择、排序、过滤和分页都可以有统一约定。

换句话说，JSON 是数据格式，JSON:API 是一套 API 响应结构规则。

JSON:API 长什么样

一个简单的 JSON:API 响应通常会用 data 包裹资源：

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API basics"
    }
  }
}

其中 type 和 id 标识资源，attributes 放普通字段，relationships 可以描述与其他资源的关系，避免每个接口都临时发明一套嵌套结构。

为什么团队会使用 JSON:API

当一个产品有多个客户端或很多资源类型时，JSON:API 的价值更明显：

• 前端可以按统一规则解析响应。
• API 错误结构更稳定。
• 分页、关联资源和链接不必每个接口重新设计。
• 文档能更多关注字段含义，而不是重复解释响应外壳。

它适合长期维护、多人协作、客户端较多的 API。

什么时候不一定需要 JSON:API

JSON:API 的结构比普通 JSON 响应更严格。对于很小的内部接口，简单 JSON 可能更直观、更易维护。

如果 API 有大量资源、关系和长期契约，可以考虑 JSON:API；如果只是少量端点，额外的 data、attributes、relationships 可能会增加理解成本。

调试建议

查看 JSON:API 响应时，先关注 data、attributes、relationships、included 和 errors。可以把示例粘贴到 JSON 格式化工具 中展开结构，再和文档或 Schema 对照。