APIレスポンスのJSONを効率的に読み解く

まずは整形する

APIレスポンスは1行で返ってくることがほとんど。最初にやるべきはインデント整形です。本ツールに貼り付けてスペース2で整形すると、構造が即座に見えるようになります。

整形すると見えてくるのが「最上位がオブジェクト{}か配列[]か」です。これがAPIの設計思想を表しています。

• ・最上位がオブジェクト: data・meta・errorなどのキーで包んでデータを返すスタイル。GitHub・Stripe・多くのモダンAPIが採用。
• ・最上位が配列: 一覧取得APIで、要素の配列を直接返すスタイル。シンプルだが、エラー時の表現がない欠点があります。

data / meta / pagination の3層構造

モダンなAPI（JSON:API仕様、GitHub REST v3など）は次のような3層構造を採用しています。

一覧APIではこの形が多いです。data以外を見落とすと「全件取得した」と思って実は最初の20件だけだった、というミスが起きます。total件数とpage情報は必ず確認しましょう。

null・undefined・空配列の違い

APIレスポンスを読むときに混同しがちな3つの「無い」状態を区別できると、エラーが激減します。

• ・キーが存在し、値がnull ({ "name": null }): キーは設計上存在するが、値が未設定・該当なし。
• ・キー自体が存在しない ({}): そもそも該当する属性がない。オプション値で省略されたケース。
• ・キーが存在し、空配列 ({ "tags": [] }): 配列の入れ物はあるが要素が0件。「タグ未設定のユーザー」など。

値を読むときは「キーが存在するかチェック → null判定 → 配列なら length 確認」の順で確認します。JavaScriptでは `data.name ?? "不明"` のように nullish coalescing 演算子を使えば短く書けます。

エラーJSONの典型パターン

APIがエラーを返すとき、JSON構造はおおむね次のいずれかです。

パターン①: errorキー

パターン②: errors配列（複数エラー対応）

パターン③: ステータスキー

HTTPステータスコード（401・403・404・422・500）と組み合わせて読むことが多いです。HTTPステータスだけ見て「失敗」と判断するのではなく、JSON本体のerror messageを必ず読みましょう。

深いネストの読み方

GitHub APIのコミット情報のように、3〜4階層のネストは珍しくありません。

整形後のインデント幅でネスト階層が見えるので、欲しい値までのパス（commit.author.name）が即座に分かります。JavaScriptで取り出すなら data.commit?.author?.name のようにオプショナルチェイニング（?.）を使うと、途中のキーが無い場合でもエラーになりません。

ページネーションとカーソル

一覧APIでは「全件返ってこないこと」が前提です。ページネーションの方式を見分けることが重要です。

• ・オフセット型: ?page=2&per_page=20。シンプルだが、データ追加中はズレが発生する。
• ・カーソル型: ?after=abc123。GitHub GraphQL・Stripe・Twitterで採用。順序が安定。
• ・リンク型（HATEOAS）: レスポンスのlinksキーに次ページのURLを含める。クライアントは次ページのURL構造を知らなくてよい。

ループでデータ取得するときは、レスポンスのpagination情報を見て「次があるか」を判定します。next === null や hasNextPage: false で停止条件を作るのが定石です。