【入門編】InsomniaのJSONPathとXPathフィルター徹底活用：巨大なAPIレスポンスから必要なデータだけを瞬時に抽出するテクニック – データベース・API管理活用バイブル

皆さん、こんにちは！ API開発の世界へようこそ。

APIのテストや連携作業を進めていると、時折、とんでもなく巨大なレスポンスに遭遇することはありませんか？数千行、時には数万行にも及ぶJSONやXMLのデータ。その中から、たった一つのIDや特定のステータス値を探し出すために、画面をスクロールしまくり、Ctrl+F（Command+F）を連打する……。

「ああ、この作業、どうにかならないものか…」

そんな風に感じた経験があるなら、今日の記事はまさにあなたのためのものです。Insomniaという強力なAPIクライアントが秘める「JSONPath」と「XPath」という魔法の杖を使いこなせば、巨大なAPIレスポンスの海の中から、必要なデータだけを瞬時に、そして正確に引き抜くことができるようになります。

これをマスターすれば、毎日のAPI開発・テスト作業が劇的に楽になりますよ。さあ、一緒にこの強力なテクニックを身につけて、APIマスターへの一歩を踏み出しましょう！

—

1. Insomniaとは？API開発・テストの頼れる相棒

まず、今回の主役である「Insomnia」について、簡単におさらいしましょう。

Insomniaは、API（Application Programming Interface）の設計、開発、テストを効率的に行うためのデスクトップアプリケーションです。REST、GraphQL、gRPCなど、様々な種類のAPIリクエストを直感的なUIで作成・送信し、そのレスポンスを確認できます。

Insomniaが多くのエンジニアに愛される理由:

直感的なUI: 迷うことなくAPIリクエストを作成・管理できます。
豊富な機能: 環境変数、認証、テストスクリプト、そして今回紹介するフィルタリング機能など、開発に必要な機能が充実しています。
Request Chaining: あるリクエストのレスポンスから抽出した情報を、次のリクエストに自動的に引き渡すことができ、一連のAPIフローのテストに非常に便利です。
コード生成: 作成したリクエストを様々なプログラミング言語のコードとして生成できるため、開発効率が向上します。

インストール方法

Insomniaのインストールは非常に簡単です。

1. Insomniaの公式サイト（

The Collaborative API Development Platform

Leading Open Source API Development Platform for HTTP, REST, GraphQL, gRPC, SOAP, and WebSockets

(https://insomnia.rest/)）にアクセスします。
2. お使いのOS（Windows, macOS, Linux）に応じたインストーラーをダウンロードします。
3. ダウンロードしたファイルを実行し、指示に従ってインストールを進めます。

これで、あなたのPCに強力なAPIクライアントが準備できました！

最も重要な基礎セットアップ：最初のAPIリクエスト

Insomniaを起動したら、まずは簡単なAPIリクエストを送ってみましょう。

1. 左側のサイドバーにある「+」ボタンをクリックし、「New Request」を選択します。
2. リクエスト名（例: `Get Public Todos`）を入力し、「Create」をクリックします。
3. 表示されたリクエストエディタのURLフィールドに、以下の公開APIのURLを入力します。

https://jsonplaceholder.typicode.com/todos

4. メソッドが「GET」になっていることを確認します。
5. 右上の「Send」ボタンをクリックします。

数秒後、画面右側の「Response」ペインに、ずらりと並んだJSONデータが表示されるはずです。これがAPIからのレスポンスです。

[
{
“userId”: 1,
“id”: 1,
“title”: “delectus aut autem”,
“completed”: false
},
{
“userId”: 1,
“id”: 2,
“title”: “quis ut nam facilis et officia qui”,
“completed”: false
},
// … 多数のtodoアイテムが続く
{
“userId”: 10,
“id”: 200,
“title”: “ipsam aperiam voluptates qui”,
“completed”: false
}
]

今回のテーマは、まさにこの「ずらりと並んだデータ」の中から、欲しいものだけをスマートに選び出す方法です！

—

2. なぜJSONPath/XPathが必要なのか？巨大レスポンスの「痛み」と「解決策」

APIからのレスポンスは、しばしばリスト形式で大量のデータを含んでいます。例えば、ECサイトの商品一覧、SNSのタイムライン、ユーザー管理システムにおける全ユーザー情報など、考えればキリがありません。

想像してみてください。数千の商品情報が詰まったJSONデータが返ってきたとします。あなたは、その中から「価格が1000円以下の商品」や「特定のカテゴリに属する商品」の「商品ID」だけが必要だとします。

手動で一つ一つ見ていくのは、時間の無駄ですし、ミスの元にもなりますよね。まさに、宝の山から砂金を探すようなものです。

ここで登場するのが「JSONPath」と「XPath」です。

JSONPath: JSONデータの中から特定の要素を抽出するためのクエリ言語です。
XPath: XMLデータの中から特定の要素を抽出するためのクエリ言語です。

これらは例えるなら、「データの住所指定システム」です。巨大なデータ構造の中から、私たちが欲しいデータがどこにあるのかを、まるで郵便番号と住所を組み合わせて指定するように、正確に指し示すことができるのです。

Insomniaには、このJSONPathとXPathのフィルター機能がビルトインされています。これを使えば、手動でのデータ探しに終止符を打ち、あなたの作業効率は劇的に向上します。

—

3. InsomniaでJSONPath/XPathフィルターを使いこなす準備

InsomniaでJSONPathやXPathを使うのは非常に簡単です。先ほどGETリクエストを送ったレスポンスペインに注目してください。

1. レスポンスペインの上部にある「Filter」という入力フィールドを見つけてください。
2. デフォルトでは空欄になっているか、`$.`（JSONPathのルート）が入力されているかもしれません。

この「Filter」フィールドに、JSONPathまたはXPathの式を入力するだけで、レスポンスデータがリアルタイムにフィルタリングされます。JSON形式のレスポンスにはJSONPathを、XML形式のレスポンスにはXPathを使用します。Insomniaは自動的に形式を判断してくれます。

さあ、準備は整いました。まずはJSONPathからその強力さを体験していきましょう！

—

4. JSONPath徹底マスター！必要なJSONデータをピンポイント抽出

JSONPathは、JavaScriptのオブジェクトアクセスに似た直感的な構文を持っています。基本は「`.`」でオブジェクトのプロパティにアクセスし、「`[]`」で配列の要素やインデックスにアクセスします。

練習用に、以下のJSONデータがあると仮定して進めていきましょう。これは、先ほどjsonplaceholderから取得した`todos`に似た、より複雑な構造を持つサンプルです。

// HelloWorld用サンプルJSON (InsomniaのBodyタブでRaw JSONとして貼り付けてもOK)
{
“store”: {
“book”: [
{
“category”: “reference”,
“author”: “Nigel Rees”,
“title”: “Sayings of the Century”,
“price”: 8.95,
“tags”: [“classic”, “quote”]
},
{
“category”: “fiction”,
“author”: “Evelyn Waugh”,
“title”: “Sword of Honour”,
“price”: 12.99,
“tags”: [“war”, “historical”]
},
{
“category”: “fiction”,
“author”: “Herman Melville”,
“title”: “Moby Dick”,
“isbn”: “0-553-21311-3”,
“price”: 8.99,
“tags”: [“adventure”, “classic”]
},
{
“category”: “fiction”,
“author”: “J. R. R. Tolkien”,
“title”: “The Lord of the Rings”,
“isbn”: “0-395-19395-8”,
“price”: 22.99,
“tags”: [“fantasy”, “epic”]
}
],
“bicycle”: {
“color”: “red”,
“price”: 19.95
},
“staff”: [
{“name”: “Alice”, “role”: “manager”},
{“name”: “Bob”, “role”: “sales”}
]
},
“metadata”: {
“version”: “1.0”,
“updated_at”: “2023-10-27T10:00:00Z”
}
}

Insomniaの「Request Body」を「JSON」に設定し、上記のJSONを貼り付けてください（GETリクエストではなく、例えば適当なURLにPOSTリクエストを送る形でも構いません。重要なのは、このJSONがレスポンスとしてInsomniaに表示されることです）。

それでは、Filterフィールドに以下のJSONPathを入力して、結果を確認していきましょう。

4.1. 基本の「`$`」「`.`」「`[]`」：オブジェクトと配列へのアクセス

`$`: ドキュメントのルート要素を表します。全てのJSONPath式は`$`から始まります。
`.` (ドット記法): オブジェクトのプロパティにアクセスします。
`[]` (ブラケット記法): 配列の要素（インデックス指定）や、プロパティ名に特殊文字が含まれる場合などに使います。

4.2. ワイルドカード「“」：全てのプロパティ/要素

ワイルドカードは、オブジェクトの全てのプロパティ、または配列の全ての要素を選択したい場合に便利です。

| 構文 | 説明 | 例 | 結果 |
| :——————– | :————————————————- | :——————————– | :—————————————————————– |
| `$.object.` | オブジェクトの全てのプロパティの値 | `$.store.bicycle.` | `[“red”, 19.95]` |
| `$.array[]` | 配列の全ての要素 | `$.store.book[]` | 全ての本のオブジェクトの配列 |
| `$.array[].property` | 配列の全ての要素の特定のプロパティの値 | `$.store.book[].title` | `[“Sayings of the Century”, “Sword of Honour”, …]` |

4.3. 再帰的探索「`..`」：どこにあっても見つけ出す

「`..`」は、パスのどこかに存在する特定のプロパティを検索したい場合に非常に役立ちます。JSONの構造が深く、特定のプロパティがどこにあるか正確なパスが分からない場合に強力です。

4.4. フィルター式「`?()`」：条件に合致する要素のみ抽出

最も強力な機能の一つがフィルター式です。配列の中から特定の条件を満たす要素だけを抽出できます。フィルター式は`?()`で囲み、`@`は現在の要素を表します。

4.5. 複数の要素を選択「`[,]`」：特定の要素を複数指定

配列から複数の特定のインデックスの要素を選択したい場合に利用します。

| 構文 | 説明 | 例 | 結果 |
| :—————– | :—————————- | :———————– | :——————————— |
| `$.array[index1,index2]` | 複数のインデックスの要素を選択 | `$.store.book[0,3].title` | `[“Sayings of the Century”, “The Lord of the Rings”]` |

JSONPathは非常に強力で、これらの構文を組み合わせることで、どんなに複雑なJSON構造からでも、必要なデータをピンポイントで取り出すことができます。まさに「宝探し」のプロフェッショナルになれるツールですね！

—

5. XPath徹底マスター！XMLデータの壁を打ち破る

JSONPathがJSONデータの住所指定だったのに対し、XPathはXMLデータの住所指定システムです。XMLはHTMLと似たツリー構造を持つため、XPathもその構造に沿ったパスを記述します。

練習用に、以下のXMLデータがあると仮定して進めていきましょう。

Nigel Rees
Sayings of the Century 8.95

Evelyn Waugh
Sword of Honour 12.99

Herman Melville
Moby Dick 8.99

J. R. R. Tolkien
The Lord of the Rings 22.99
19.95

Alice
manager

Bob
sales

Insomniaの「Request Body」を「XML」に設定し、上記のXMLを貼り付けてください。

それでは、Filterフィールドに以下のXPathを入力して、結果を確認していきましょう。

5.1. 基本パス「`/`」「`//`」：ルートと任意の位置からの探索

`/`: ルート要素からパスを始めます。絶対パスを指定します。
`//`: ドキュメント内の任意の場所から要素を検索します。相対パスのように使えます。

5.2. 属性の選択「`@`」：要素の属性値にアクセス

XMLの属性値にアクセスするには「`@`」を使います。

5.3. 述語（条件）「`[]`」：条件に合致する要素のみ抽出

XPathの述語は、JSONPathのフィルター式に似ており、`[]`の中に条件を記述します。

XPathも非常に強力で、XML構造の深い部分に隠れた情報でも、正確に抽出することができます。APIがXML形式のレスポンスを返す場合でも、もうデータ探しに困ることはありませんね！

—

6. 実践！抽出したデータをAPIテストやRequest Chainingに活用する

JSONPathやXPathで必要なデータを抽出できるようになったら、次はそれをInsomniaの他の強力な機能と連携させて、日々のAPI作業をさらに効率化しましょう。特にRequest Chaining（リクエストの連鎖）とテストでの活用は、あなたのワークフローを劇的に改善します。

6.1. 抽出したデータを環境変数へ格納：Request Chainingの第一歩

API連携では、あるリクエストのレスポンスで得られた情報（例: 認証トークン、作成されたリソースのIDなど）を、次のリクエストのヘッダーやボディに含めて送信する、というパターンが頻繁に発生します。Insomniaでは、この処理を「Response > Body Attribute」というテンプレートタグを使って自動化できます。

シナリオ例:
1. ユーザー登録APIを呼び出す。
2. レスポンスで返されるユーザーIDを抽出する。
3. そのユーザーIDを使って、ユーザー詳細情報を取得するAPIを呼び出す。

手順:

1. ユーザー登録APIリクエスト（例: POST /users）を作成し、送信します。
例えば、以下のようなレスポンスが返ってくるとします。

{
“id”: “usr_abc123”,
“name”: “John Doe”,
“email”: “john.doe@example.com”
}

2. 抽出したいデータ（この場合は`id`）を環境変数に格納します。

Insomniaの「Response」ペインで、レスポンスが表示されていることを確認します。
レスポンスペインの上部にある「Test」タブをクリックします（バージョンによっては「Timeline」タブの右にある歯車アイコンから「Add Test Script」を選択するかもしれません）。
テストスクリプトエディタが開いたら、以下のJavaScriptコードを記述します。

// 抽出したIDを環境変数にセットする例

// レスポンスのJSONをパース
const responseBody = JSON.parse(response.body);

// JSONPathを使ってIDを抽出
const userId = responseBody.id; // もしネストされているなら responseBody.data.id のように記述

// 環境変数にセット
// ここではグローバル環境にセットしていますが、特定の環境にセットすることも可能です。
// 例: req.setEnvironmentVariable(‘userId’, userId);
// あるいは、Insomniaのビルトイン機能を使う方がよりシンプルです。
// これはJSテストスクリプトでの例ですが、InsomniaはGUIでより簡単にできます。

// —- GUIでの設定方法 (こちらを推奨) —-
// 1. レスポンスを受け取ったリクエストタブの「Timeline」ペインに移動します。
// 2. 「Timeline」タブのすぐ下の「Test」タブの隣に「Body」タブ（またはResponse Body）があることを確認します。
// 3. 画面中央上部にある「Environments」ドロップダウン（No Environmentなど）をクリックし、
// 「Manage Environments」を選択します。
// 4. 新しい環境を作成するか、既存の環境を選択します。
// 5. 環境設定画面で、`userId`のようなキーを追加します。値はここでは空で構いません。
// 6. ユーザー登録APIのリクエストタブに戻ります。
// 7. レスポンスペインの「Body」タブを表示した状態で、抽出したい値（例: “usr_abc123″）を右クリックします。
// 8. コンテキストメニューから「Set Environment Variable」を選択します。
// 9. 表示されるダイアログで、環境変数名（例: `userId`）と、どの環境に保存するか（例: `Base Environment`）を選択します。
// 「JSONPath」のフィールドに自動的に適切なJSONPath（例: `$.id`）が入力されているはずです。
// 10. 「Set Variable」をクリックします。
// 11. これで、リクエストを送信するたびに、レスポンスから抽出された`id`が`userId`という環境変数に自動的に格納されるようになります。

console.log(`Extracted userId: ${userId}`); // 抽出された値がコンソールに出力されることを確認

補足: InsomniaのGUIには「Response > Body Attribute」タグという非常に便利な機能があります。これを使うと、テストスクリプトを書かなくても、直接JSONPath（またはXPath）で抽出した値を環境変数に設定し、次のリクエストで参照できるようになります。
具体的な使い方は、次の「次のリクエストへの引き渡し」で説明します。

6.2. 次のリクエストへの引き渡し：Request Chainingの実現

環境変数に格納された値は、Insomniaのどのリクエストからでも参照できます。

1. ユーザー詳細取得APIリクエスト（例: GET /users/:id）を作成します。
2. URLの`:id`の部分に、先ほど環境変数に格納した`userId`を埋め込みます。

URLフィールドに`https://api.example.com/users/`と入力します。
続けて、`userId`環境変数を挿入します。これには、Insomniaのテンプレートタグを使います。
`https://api.example.com/users/{{ userId }}` と入力します。
`{{` と入力すると、Insomniaが利用可能な環境変数をサジェストしてくれます。

もし環境変数をGUIで設定せず、直接JSONPathで抽出したい場合は、以下のように記述することも可能です。
これは「Response > Body Attribute」テンプレートタグの例です。

https://api.example.com/users/{% response ‘body’, ‘ユーザー登録リクエストのID’, ‘$.id’, ‘json’ %}

`’ユーザー登録リクエストのID’`の部分は、Insomniaのサイドバーに表示されている対象リクエストの名前（またはID）に置き換えてください。
`’$.id’` は、抽出したい値のJSONPathです。
`’json’` は、レスポンスの形式がJSONであることを示します。XMLの場合は`’xml’`とします。

3. このリクエストを送信すると、`{{ userId }}`の部分が、前のリクエストで抽出された実際のIDに置き換わって送信されます。

これで、複数のAPIリクエストが連携して動作する「Request Chaining」が実現しました！認証トークンを使った保護されたAPIへのアクセスなど、複雑なAPIフローのテストが非常に簡単になります。

6.3. テストスクリプトでの活用：レスポンス検証の自動化

InsomniaにはJavaScriptベースのテストスクリプト機能があり、レスポンスの内容を自動的に検証できます。ここでもJSONPathで抽出したデータが役立ちます。

シナリオ例:
ユーザー登録APIのレスポンスで、返ってきたIDが正しい形式であるか、または登録されたユーザー名が期待通りであるかを検証する。

手順:

1. ユーザー登録APIリクエストの「Test」タブに移動します。
2. 以下のJavaScriptコードを記述します。

// レスポンスのJSONをパース
const responseBody = JSON.parse(response.body);

// JSONPathを使ってIDと名前を抽出
const userId = responseBody.id;
const userName = responseBody.name;

// レスポンスのステータスコードが201 (Created) であることを検証
expect(response.statusCode).to.equal(201);

// 抽出したIDが特定のプレフィックスで始まることを検証
expect(userId).to.match(/^usr_/); // 例: “usr_abc123” の形式かチェック

// 抽出したユーザー名が期待通りであることを検証
expect(userName).to.equal(‘John Doe’);

// ユーザーが存在することを確認（例として、idが空でないこと）
expect(userId).to.exist;

console.log(‘API response successfully validated!’);

`expect()`関数は、Insomniaに組み込まれているChaiアサーションライブラリの一部です。
`response.body`はレスポンスの生データ文字列です。`JSON.parse()`でJavaScriptオブジェクトに変換してからJSONPathの要領でアクセスします。

3. リクエストを送信すると、テストスクリプトが実行され、その結果がテストタブに表示されます。パスすれば緑色、失敗すれば赤色で表示され、何が問題だったかを一目で確認できます。

このように、JSONPathやXPathでデータを抽出し、それを環境変数やテストスクリプトで活用することで、API開発・テストの自動化と品質向上を大きく図ることができます。もう手動でデータをコピペしたり、目視で確認したりする必要はありません！

—

7. さらなる高みへ：パフォーマンスとAPI設計への示唆

JSONPathやXPathを使いこなすことは、目の前のAPIテスト作業を効率化するだけでなく、より広い視野でAPIと向き合うための重要な視点を与えてくれます。

API設計の視点：巨大レスポンスを避ける工夫

Insomniaのフィルタリング機能は強力ですが、そもそもAPIが巨大なレスポンスを返すこと自体が、パフォーマンスや運用上の課題につながることが多いです。

ネットワーク帯域の消費: クライアントとサーバー間で大量のデータが送受信されるため、ネットワーク負荷が増大します。
サーバー負荷: サーバー側で大量のデータを生成・整形する処理は、CPUやメモリを消費します。
クライアント処理負荷: クライアント側でも、巨大なJSON/XMLをパースし、メモリに展開するのに時間がかかります。特にモバイルアプリなどリソースが限られた環境では顕著です。

優秀なAPIアーキテクトとしては、以下の点を考慮すべきです。

ページネーション (Pagination): 大量のリストデータを返す場合は、ページネーションを導入し、一度に返すデータ量を制限します（例: `?page=1&limit=20`）。
フィールド選択 (Field Selection): クライアントが本当に必要なフィールドだけを指定して取得できるようにする仕組みです（例: `?fields=id,title,price`）。GraphQLのようなAPIスタイルは、このフィールド選択を柔軟に行えるように設計されています。
条件付き取得: 特定の条件に合致するデータのみを返すフィルター機能をAPI側に実装します（例: `?category=fiction&price_lte=10`）。

InsomniaでJSONPath/XPathを使う際に「毎回この長いパスを入力しないと目的のデータにたどり着けない…」と感じたら、それはAPI設計自体に改善の余地があるのかもしれません。クライアント側の苦労を減らすようなAPI設計を心がけることが、真のAPIマスターへの道です。

エラーハンドリングとセキュリティ

存在しないパス: JSONPath/XPathで存在しないパスを指定した場合、Insomniaのフィルターは何も表示しないか、空の配列/オブジェクトを返します。これはエラーではありませんが、意図しない結果でないか確認しましょう。
機密情報の抽出: レスポンスに機密情報（パスワードハッシュ、APIキーなど）が含まれている場合、JSONPath/XPathで抽出して環境変数に格納する際には、その環境が安全に管理されているか細心の注意を払ってください。本番環境で使うAPIキーなどをテスト環境の環境変数に誤って格納しないよう、環境管理は慎重に行うべきです。

—

まとめ

本日は、InsomniaのJSONPathとXPathフィルター機能を徹底的に活用し、巨大なAPIレスポンスから必要なデータを瞬時に抽出するテクニックについて解説しました。

JSONPathはJSONデータに、XPathはXMLデータに特化した「データの住所指定システム」であり、あなたのAPIテスト・開発作業を劇的に効率化します。
基本的な構文から、ワイルドカード、再帰的探索、条件によるフィルタリングまで、様々な使い方を学びました。
抽出したデータは、Insomniaの環境変数機能やテストスクリプトと連携させることで、Request Chainingや自動テストといった、より高度なAPIワークフローを構築できます。
また、これらのフィルタリング機能は、API設計の改善点を見つけるヒントにもなります。

これであなたも、もう巨大なAPIレスポンスの海で溺れることはありません。必要なデータに一直線にたどり着く、効率的なAPIマスターへの一歩を踏み出しましたね！

この知識を現場で積極的に活用し、あなたの開発ライフをより豊かなものにしてください。応援しています！