JSON API データ契約設計の要点

要点：ページネーションや命名の細部を論じる前に、レスポンスエンベロープ、エラー形式、ID と時刻の表現、null と欠落の意味論を契約として固定しましょう。トップレベルは常に data エンベロープで包み、後からページネーションやトレース ID を既存の呼び出し元を壊さずに追加できるようにします。

API 設計に標準の答えはありませんが、「一度選ぶと取り戻しにくい」決定がいくつかあり、最初の一行を書く前に考えておくのが賢明です。

1. レスポンスを包むか包まないか

三つのスタイル：

复制// スタイル A：裸のレスポンス
{ "id": 1, "name": "山田" }

// スタイル B：data エンベロープ
{ "data": { "id": 1, "name": "山田" } }

// スタイル C：data + メタデータ
{ "data": { "id": 1, "name": "山田" }, "meta": { "requestId": "a1b2" } }

推奨：リストも詳細も一律に data エンベロープを使い、トップレベルを配列にしないこと。そうすれば後からページネーションやトレース ID を足しても契約は壊れません。

2. エラー形式：RFC 9457 をコピーする

独自のエラー構造を発明するのは、協業コストの巨大な源です。RFC 9457（RFC 7807 を置き換える）は application/problem+json を定義しています。

复制{
  "type": "https://bbdrug.com/problems/insufficient-balance",
  "title": "残高不足",
  "status": 422,
  "detail": "口座残高は 12.00 元、今回の引き落としには 30.00 元が必要です",
  "instance": "/accounts/A1001/payments/p-889",
  "balance": "12.00",
  "required": "30.00"
}

拡張フィールド（上の balance / required など）は仕様で許されており、フロントエンドは detail のテキストをパースする代わりに、それらを使って精密なメッセージを組み立てられます。

3. ページネーション：カーソルがオフセットに勝る

复制// オフセットページネーション
{ "data": [], "page": { "offset": 40, "limit": 20, "total": 137 } }

// カーソルページネーション
{ "data": [], "page": { "nextCursor": "eyJpZCI6MTAwfQ", "hasMore": true } }

推奨：管理画面の表（ページジャンプと総件数が必要）にはオフセット、ユーザー向けの無限フィードにはカーソルを使います。

4. ID と時刻

4.1 ID は常に文字列

理由は型の記事で扱いました。JavaScript 側では 2^53 を超える値が静かに精度を失います。 現在の ID が小さな自動増分整数でも、文字列にしておけば後でスノーフレーク ID に切り替える余地が残ります。

复制{ "id": "1000000000000000001" }

4.2 時刻には RFC 3339 文字列

复制{
  "createdAt": "2026-10-30T10:41:45+08:00",
  "updatedAt": "2026-10-30T02:41:45Z"
}

• ミリ秒タイムスタンプの数値は使わない。読みにくく、単位（秒/ミリ秒）を頻繁に間違えます。
• タイムゾーンを明示する。Z かオフセットのどちらかで。タイムゾーンのない「ローカル時刻」は決して使わない。
• フィールドは一律 xxxAt と命名し、一目で時刻点だと分かるようにする。

5. null と欠落

どちらかを選び、ドキュメントに書き込まなければなりません。

方法 A の問題は、PATCH で「省略」と「null として送信」が異なる意味になり、誤解しやすいことです。 方法 B の問題は、フロントエンドの JSON.stringify が値 undefined のフィールドを落とし、たまたま意味論と一致することです。

実践的な推奨：

• レスポンスボディには方法 A（null は明確に値なしを意味し、フロントエンドは undefined を区別する必要がない）。
• リクエストボディ（特に PATCH）には方法 B を使い、Merge Patch か JSON Patch と組み合わせて意味論を明示する。

6. フィールド命名と構造

空配列に null ではなく [] を返すことは非常に重要です。フロントエンドの data.items.map(...) が null でクラッシュしません。

7. 進化の戦略

規律の三つの規則：

1. クライアントは未知のフィールドに寛容でなければならない（additionalProperties: false で自分を縛らない）。
2. クライアントは未知の enum 値にフォールバック分岐を持たなければならない。
3. 非推奨フィールドは少なくとも一つのメジャーバージョンは残し、レスポンスヘッダーかドキュメントで Deprecation をマークする。

8. 完全な例

复制{
  "data": [
    {
      "id": "1001",
      "name": "JSON 徹底ガイド",
      "price": "89.50",
      "tags": ["json", "spec"],
      "publishedAt": "2026-09-01T00:00:00+08:00",
      "author": null
    }
  ],
  "page": { "nextCursor": null, "hasMore": false },
  "meta": { "requestId": "req-7f3a", "tookMs": 12 }
}

このレスポンスは上のすべての慣習を反映しています。data エンベロープ、文字列 ID、文字列の金額、タイムゾーン付きタイムスタンプ、 欠落を意味する null、空配列、カーソルページネーション、可観測性情報の meta。

9. チェックリスト

• [ ] トップレベルは配列でなく、一律に data エンベロープを使う。
• [ ] エラー応答は RFC 9457 に従い、安定した type を含む。
• [ ] ページネーションの形が業務シナリオに合う。
• [ ] ID は文字列で、時刻は RFC 3339。
• [ ] null と欠落の意味論がドキュメントに書かれている。
• [ ] 命名スタイルがプロジェクト全体で統一され、enum は小文字文字列。
• [ ] クライアントが未知フィールドと未知 enum 値のフォールバックを持つ。
• [ ] 破壊的変更はバージョニングか二重書き込みの移行を通す。

FAQ

進化可能な JSON API はどう設計すればよいですか？

リストも詳細も一律に data エンベロープで包み、トップレベルを配列にしないことで、契約を壊さずにページネーションとトレース ID を足せます。ID は文字列、時刻は RFC 3339 を使い、null と欠落の意味論をドキュメントに書きます。新しいフィールドは任意で意味的に独立に保ち、クライアントに未知フィールドと enum 値のフォールバックを持たせます。

独自のエラー形式を発明しないのはなぜですか？

独自のエラー構造を発明するのは協業コストの巨大な源です。RFC 9457 の application/problem+json をコピーし、問題を安定した type で識別し、balance や required のような拡張フィールドを許せば、フロントエンドは detail のテキストをパースせずに精密なメッセージを組み立てられます。

すべてのエンドポイントがカーソルページネーションを使うべきですか？

いいえ。管理画面の表はページジャンプと総件数が必要なのでオフセットの方が合います。ユーザー向けの無限フィードはカーソルを使うべきで、深いページでも安定し、データ変化時の重複や欠落を避けられます。シナリオがページジャンプと総件数を必要とするかで選んでください。