JSON:API とは？

JSON:API は、一貫したレスポンス形状で JSON ベースの API を構築するための仕様です。resource、relationship、link、error、sparse fieldset、ソート、フィルタ、ページネーションの規約を定義します。

目的は JSON を置き換えることではありません。JSON はデータ形式であり、JSON:API は API がその JSON をどう整理すべきかのルールセットです。

JSON:API の見た目

シンプルな JSON:API レスポンスは通常、resource を data オブジェクトまたは配列でラップします。

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

type と id が resource を識別します。attributes は通常のフィールドを保持します。relationships は、すべてのレスポンスでネストオブジェクトを重複させなくても他 resource への link を記述できます。

チームが JSON:API を使う理由

JSON:API は、複数のクライアントが予測可能な payload を必要とするときに有用です。

• フロントエンドアプリは共通の前提でレスポンスを parse できる。
• API error は 1 つの構造に従える。
• ページネーション、relationship、link を endpoint 間で一貫させられる。
• ドキュメントは毎回レスポンス形状を再発明するのではなく resource フィールドに集中できる。

特に大規模プロダクトでは、カスタム API 規約を減らせます。

JSON:API が過剰になり得る場合

JSON:API は多くの小さな API が必要とするより構造化されています。小さな内部サービスなら、シンプルな JSON レスポンスのほうが読みやすく保守しやすいことがあります。

resource タイプ、relationship、クライアント、長寿命契約が多い API では JSON:API を検討してください。追加の envelope と規約が一貫性より混乱を増やすなら、採用を見送ってください。

実践的なデバッグのヒント

JSON:API レスポンスを確認するときは、まず data、attributes、relationships、included、errors をチェックします。サンプルを JSON Formatter に貼り付け、ドキュメントや schema と比較する前に構造を展開してください。