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"
    }
  }]
}

上の応答には、「記事」のコレクション中で最初の 1 つが含まれます。また、そのコレクション内の以降のメンバーへのリンクも含まれます。これには、記事に関連付けられたリソース、つまり作成者とコメントも含まれます。最後に、これらのリソースのいずれかをフェッチまたは更新するために使用できるリンクが提供されています。

JSON:API はリソースの作成と更新もカバーしており、応答だけではありません。

MIME タイプ

JSON:API は IANA に適切に登録されています。メディアタイプの指定は application/vnd.api+json です。

フォーマットに関するドキュメント

JSON:API を始めるには、基本仕様のドキュメントを確認してください。

拡張機能

JSON:API コミュニティは、API が JSON:API 基本仕様で説明されている範囲を越えてクライアントに情報または機能を提供するために使用できる拡張機能のコレクションを作成しました。これらの拡張機能はプロファイルと呼ばれます。

既存のプロファイルを閲覧または新しいプロファイルを作成できます。

マイルストーン

この仕様の主なマイルストーンは次のとおりです。

2022 年 9 月 30 日: 1.1 がリリースされました。
2015 年 5 月 29 日: 1.0 がリリースされました。
2013 年 7 月 21 日: IANA へのメディアタイプの登録が完了しました。
2013 年 5 月 3 日: ドラフトの最初のリリース。

より詳細な履歴はこちらでご覧いただけます。

個々の変更の RSS フィードをこちらで購読できます。