API設計

JSON:API じぇいそんえーぴーあい

REST APIレスポンス形式リソース設計仕様標準化HATEOASシリアライゼーション

JSON:APIについて教えて

簡単に言うとこんな感じ！

JSON:APIは「APIのレスポンスの書き方をみんなで統一しようよ！」という取り決めだよ。料理のレシピに「材料はgram表記、手順は番号付きで書く」みたいなルールを決めることで、どのAPIでも同じ読み方ができるようになるってこと！

JSON:APIとは

JSON:APIは、REST APIにおけるリクエスト・レスポンスのデータ形式を標準化した仕様（スペック）です。正式名称は「JSON:API」で、コロン（:）が名前に含まれているのが特徴です。Webアプリやモバイルアプリがサーバーとやり取りするとき、「どんなJSON形式でデータを返すか」という書き方のルールを統一しています。

APIを開発するチームが異なると、同じ「ユーザー情報を返す」APIでも、レスポンスのJSON構造がバラバラになりがちです。JSON:APIはその「バラつき」を解消する共通言語として2013年に登場しました。仕様に従うと、リソース（データの単位）の表現方法、ページネーション（ページ分割）、エラー形式、リレーション（関連データの扱い）などが統一されます。

実務では、フロントエンド（画面側）とバックエンド（サーバー側）の開発チームが別れているプロジェクトで特に威力を発揮します。「どんな形でデータを返すか」の議論が不要になり、開発速度が上がるというメリットがあります。

JSON:APIの構造と主なルール

JSON:APIのレスポンスは、いくつかの決まったキーで構成されます。

キー名	役割	必須/任意
`data`	メインのリソースデータ	必須
`errors`	エラー情報（dataと共存不可）	任意
`meta`	ページ数・件数などの補足情報	任意
`included`	関連リソースの埋め込みデータ	任意
`links`	ページネーション用URLなど	任意
`jsonapi`	仕様バージョン情報	任意

レスポンスの具体例

{
  "data": {
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:APIとは何か",
      "body": "本文テキスト..."
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    }
  },
  "included": [
    {
      "type": "people",
      "id": "9",
      "attributes": {
        "name": "山田 太郎"
      }
    }
  ]
}

リソースオブジェクトの3点セット

JSON:APIでは data の中身を「リソースオブジェクト」と呼び、必ず次の3つを持ちます。

type — リソースの種類（例: "articles", "users"）
id — リソースの一意な識別子
attributes — そのリソースが持つ属性（名前・タイトルなど）

覚え方

「タイプ・アイディー・アトリビュート」＝「種類・番号・中身」
図書館の本カードで「ジャンル・請求番号・タイトル」を書くイメージで覚えよう！

歴史と背景

2013年 — Ember.jsコアチームのYehuda Katz氏とSteve Klabnik氏が草案を発表。Ember Dataフレームワークとの連携を意識して設計
2015年 — バージョン1.0が正式リリース。「ベストプラクティスを集約した安定仕様」として広く認知される
2015〜2018年 — Ruby on Rails向けの JSONAPI::Resources、JavaScript向けの json-api-serializer など、多数のライブラリが登場
2022年 — バージョン1.1リリース。プロファイル（拡張仕様）の仕組みや lid（ローカルID）などが追加される
現在 — GraphQLの台頭により選択肢は増えたが、REST APIの標準化手段として根強い支持を持つ

他のAPI設計スタイルとの比較

JSON:APIは「REST + 標準フォーマット」のアプローチです。同じくAPIの設計に使われるGraphQLやOpenAPI仕様と比較してみましょう。

JSON:APIとOpenAPIの関係

JSON:APIとOpenAPIは競合ではなく補完関係にあります。JSON:APIが「データの形式ルール」を決める仕様であるのに対し、OpenAPIは「どんなエンドポイントが存在するかを文書化する」仕様です。両方を採用することで「形式も統一・文書も整備」という状態を実現できます。

規格・RFC番号	内容
RFC 8259	JSON（JavaScript Object Notation）のデータ形式標準
RFC 6570	URI Template（JSON:APIのリンク生成に関連）
RFC 7807	Problem Details for HTTP APIs（エラー形式の標準化）