リストとオブジェクトのドキュメントパターン

API と設定ファイルはトップレベルの形を選び分けます。パターンを認識すると、ドキュメントの読み方が速くなり、一貫したエンドポイント設計にもつながります。

ルート配列

有効な JSON はトップレベルで配列になり得ます。

[
  {"id": 1, "name": "Alpha"},
  {"id": 2, "name": "Beta"}
]

小さな静的リストやバッチエクスポートでよく見られます。多くの REST API は、メタデータの置き場を確保するためオブジェクトラッパーを好みます。

エンベロープオブジェクト

リストデータとメタデータをラップします。

{
  "data": [
    {"id": 1, "name": "Alpha"}
  ],
  "meta": { "total": 42, "page": 1 }
}

名前は様々です（data、items、results、records）。考え方は同じ: 1 つのオブジェクトにpayload + コンテキスト。

ページネーションフィールド

よくあるパターン:

{
  "items": [],
  "nextCursor": "abc123",
  "hasMore": true
}

または page、pageSize、totalCount を使うオフセット方式。クライアントはフィールド名を決め打ちしないで — 各 API の仕様を読んでください。

オブジェクトのみのドキュメント

設定は通常、単一のオブジェクトです。

{
  "theme": "dark",
  "features": { "beta": false }
}

ルートに配列はなく、ネストしたオブジェクトで設定をグループ化します。

形の選び方

オブジェクトルートを選ぶとき	ルート配列でよいとき
データと並べてページネーションやエラーが必要	固定の小さなカタログ
バージョンや links オブジェクトが登場	内部ツール、fixture
複数リソース型が 1 エンドポイントを共有	シンプルな公開データフィード

自社 API 内の一貫性は、他製品のフィールド名をコピーするより重要です。