JSON:API — 使用 JSON 建構 API 的規範

如果您曾經與您的團隊爭論 JSON 回應的格式，JSON:API 可以幫助您停止無謂的爭論 (bikeshedding)，並專注於真正重要的事情：您的應用程式。

透過遵循共同的慣例，您可以提高生產力，利用通用的工具和最佳實務。圍繞 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 規範中未描述的資訊或功能。這些擴充功能稱為設定檔 (Profiles)。

您可以瀏覽現有的設定檔或建立新的設定檔。

里程碑

此規範的主要里程碑包括

2022-09-30：1.1 正式版發布。
2015-05-29：1.0 正式版發布。
2013-07-21：在 IANA 完成媒體類型註冊。
2013-05-03：草案初版發布。

更完整的歷史記錄可在這裡找到。

您可以在這裡訂閱個別變更的 RSS Feed。