APIレスポンスのJSONを調べる実践ワークフロー — 整形→構造把握→差分比較→パス抽出

APIを叩いたらレスポンスの値が想定と違う、本番と検証環境で同じエンドポイントなのに返ってくるデータが微妙に違う——こうした場面でJSONの中身をただ眺めるだけでは原因になかなかたどり着けません。

この記事では、実際のデバッグシーンを想定して「整形→構造把握→差分比較→パス抽出」という4段のワークフローを紹介します。それぞれの段階でどのツールを使い、次に何をするかという流れを追っていきます。

出発点: 圧縮されたJSONが読めない

APIレスポンスはブラウザの開発者ツールやcurlコマンドで確認できますが、多くの場合改行やインデントが一切ない状態で返ってきます。1行に詰め込まれた長いJSONは、目視で構造を追うのがほぼ不可能です。

まず最初にやるべきは整形です。JSON整形ツールに貼り付ければ、インデントが揃った読みやすい形に変換できます。同時に構文エラーがあればその場で検出されるため、「そもそも正しいJSONとして返ってきているか」の確認も兼ねられます。

APIが500エラーやパースエラーを返している場合、レスポンスボディがJSONではなくHTMLのエラーページだったというケースも珍しくありません。整形段階でエラーが出た時点で、まずそこを疑うのが近道です。

構造を把握する: ネストが深いデータをツリーで見る

整形しただけでは、ネストが深いレスポンスの全体像はまだつかみにくいままです。特に配列の中にオブジェクトが入り、そのオブジェクトの中にさらに配列が入っているような構造では、どの階層にどの項目があるのか目で追うだけでは把握しづらくなります。

ここでJSONツリービューアを使うと、階層を折りたたみながら構造を確認できます。目的のデータがどの階層にあるかを先に把握しておくと、後の作業でパスを指定する際に迷わなくなります。

例えば、ユーザー一覧を返すAPIで各ユーザーの住所情報を確認したい場合、まずツリーで「users配列の各要素にaddressオブジェクトがあり、その中にprefectureとcityがある」という構造を掴んでから次のステップに進みます。

環境間の差分を見つける

想定と違う値が返ってくる原因の切り分けでよくあるのが、環境ごとの比較です。本番環境と検証環境、あるいは修正前と修正後のレスポンスを並べて、どこが変わったのかを特定したい場面です。

目視での比較は、値が一つ二つ違うだけでも見落としやすく、フィールドの並び順が違うだけで「差分がある」ように錯覚してしまうこともあります。JSON比較ツールを使えば、追加・削除・変更された箇所を自動で検出して一覧表示できるため、この錯覚を避けられます。

このステップで「どのフィールドに差分があるか」が絞り込めると、次にそのフィールドだけを追いかければよくなり、調査範囲が一気に狭まります。

特定の値だけを抽出する

差分比較で問題のフィールドが絞り込めたら、次はそのフィールドの値をピンポイントで確認する段階です。巨大なレスポンスの中から特定の項目だけを毎回目で探すのは非効率ですし、配列の要素数が多い場合はなおさらです。

こうした場面で使うのがJSONパス検索ツールです。JSONPathというクエリ言語を使うと、$.users[0].address.prefectureのような指定で、ネストされた特定の値だけを抽出できます。配列全体から特定条件に合う要素だけを取り出すような指定にも対応しているため、「住所情報を持つユーザーだけ一覧化したい」といった絞り込みにも使えます。

一度パスの書き方を覚えてしまえば、同じ構造のレスポンスを何度も確認するときにいちいちツリーを開いて目で探す手間が省けます。