Insomnia極限活用術：カスタム環境スクリプトと裏技でAPI開発を極限まで加速させる方法
テックリードの私たちが日々の開発で直面する最大のストレスの一つは、「仕様の複雑なAPIテスト」に時間を奪われることだ。動的なHMAC署名、リクエストごとのタイムスタンプ生成、さらにはレスポンスから抽出したアクセストークンを次のリクエストヘッダーに連鎖させる……。これらを毎回手動で行う人間は、このチームには一人もいらない。
APIクライアントとしてPostmanがデファクトスタンダードとして語られることが多いが、ミニマルで高速、かつGitとの親和性が極めて高い Insomnia こそ、真のエンジニアのためのツールである。今回は、InsomniaのJavaScriptベースのカスタム環境スクリプト（Pre-request / After-response）を極限まで使い倒し、複雑怪奇なAPI仕様を完全にハックする方法を伝授する。
—
1. 開発スピードを劇的に高める：隠れたキーボードショートカット
マウスに手を伸ばした瞬間から、開発のフローは途切れる。Insomniaの真価を引き出すには、キーボードショートカットの完全習得が不可欠だ。
| ショートカット (Mac / Win) | アクション | 現場での活用シーン |
| :— | :— | :— |
| `Ctrl + Space` (Cmd + Space) | 変数・タグのオートコンプリート | 環境変数やNunjucksタグを瞬時に呼び出す |
| `Ctrl + N` (Cmd + N) | 新規リクエスト作成 | エンドポイントの追加をシームレスに行う |
| `Ctrl + T` (Cmd + T) | クイックオープン（ファジー検索） | 膨大なコレクションから対象のリクエストをミリ秒で探す |
| `Ctrl + R` (Cmd + R) | リクエスト送信 | エディタから手を離さずにAPIを叩く |
| `Ctrl + L` (Cmd + L) | URLバーへフォーカス | ドメインやパスの変更へ即座に移行 |
特に `Ctrl + Space` によるオートコンプリートは、後述するカスタムスクリプト内の変数補完においても強力な武器となる。
—
2. 絶対に入れるべき「神」プラグイン群
Insomniaのコアは軽量であるべきだが、拡張性なしにモダンなAPI開発は乗り切れない。プラグインマーケットプレイスから、今すぐインストールすべき必須の3選を紹介する。
1. `insomnia-plugin-documenter`
- 概要: コレクションから美しいAPIドキュメントを自動生成する。
- 理由: Swagger/OpenAPIを書く前のプロトタイプ段階で、チーム間共有のスピードが段違いになる。
2. `insomnia-plugin-hash-digest`
- 概要: MD5, SHA-256, HMACなどのハッシュ関数をNunjucksタグとして追加する。
- 理由: スクリプトを書くまでもない単純な署名生成において、タグだけで完結させられるため可読性が爆発的に上がる。
3. `insomnia-plugin-import-cURL`
- 概要: 任意のcURLコマンドを瞬時にInsomniaのリクエスト形式に変換・インポートする。
- 理由: ドキュメントやSlackに貼られたcURLをそのまま貼り付けるだけで、設定の手間がゼロになる。
—
3. Pre-request / After-response スクリプトの極限活用
Insomniaの強力な機能の一つが、リクエスト送信前（Pre-request）とレスポンス受領後（After-response）に実行できるJavaScript環境だ。これらを駆使して、複雑な認証フローを自動化する。
実践例：HMAC-SHA256署名の動的生成とトークンの自動連鎖
以下の例は、「リクエストごとに現在時刻のタイムスタンプと、ボディを元にしたHMAC署名を生成してヘッダーに付与し、レスポンスから返却されたセッションIDを次のリクエストのために環境変数へ自動保存する」という現場でよくある高難度要件を実装したコードだ。
Pre-request スクリプト（送信前処理）
// cryptoモジュール（Insomnia組込）を使用して署名を生成
const crypto = require(‘crypto’);
// 環境変数からAPIシークレットを取得
const apiSecret = insomnia.environment.get(‘API_SECRET’);
const timestamp = Date.now().toString();
// リクエストボディを取得し、文字列化
const rawBody = insomnia.request.getBody();
const bodyString = rawBody ? (typeof rawBody === ‘string’ ? rawBody : JSON.stringify(rawBody)) : ”;
// 署名ベース文字列の作成 (Timestamp + Body)
const payload = timestamp + bodyString;
const signature = crypto
.createHmac(‘sha256’, apiSecret)
.update(payload)
.digest(‘hex’);
// リクエストヘッダーに動的パラメータをインジェクション
insomnia.request.setHeader(‘X-Timestamp’, timestamp);
insomnia.request.setHeader(‘X-Signature’, signature);
console.log(`[Pre-request] Generated Signature for timestamp: ${timestamp}`);
After-response スクリプト（受領後処理）
// レスポンスステータスが正常な場合のみ処理
if (insomnia.response.getCode() === 200) {
try {
const responseJson = JSON.parse(insomnia.response.getBody());
// レスポンスからアクセストークンを抽出
if (responseJson.data && responseJson.data.session_id) {
const sessionId = responseJson.data.session_id;
// 下流のリクエストで使用するため、環境変数に動的セット
insomnia.environment.set(‘CURRENT_SESSION_ID’, sessionId);
console.log(`[After-response] Successfully captured and stored SESSION_ID: ${sessionId}`);
}
} catch (e) {
console.error(‘[After-response] Failed to parse response body as JSON:’, e);
}
}
デバッグの裏技：コンソールログの活用
スクリプトの挙動がおかしい時、暗闇を手探りしてはいけない。Insomniaのメニューから View > Toggle DevTools を開く（または `Option + Cmd + I`）ことで、ブラウザ同様の開発者コンソールが立ち上がる。
スクリプト内での `console.log()` はすべてこのDevToolsのConsoleに出力されるため、変数のスコープやデータ構造の崩れをリアルタイムでデバッグ可能だ。
—
4. チーム開発で役立つ設定の共有化ルール
個人のローカル環境だけで動くAPIクライアントは、チーム開発において「負債」でしかない。以下のルールでコードベースとして管理する。
1. インポート・エクスポートは JSON (Insomnia v4 format) で統一
- コレクション全体をGit管理する場合、Workspaceのエクスポートファイルをプロジェクトリポジトリの `docs/api/` ディレクトリ等に配置する。
2. 機密情報は絶対にコミットしない（環境変数の分離）
- `API_KEY` や `PASSWORD` などの機密値は、ベースとなる環境変数ファイル（例: `development.env.json`）には入れず、キー名だけを定義したテンプレート (`env.template.json`) を共有する。
- 実際の値は各開発者がローカルで Insomnia の Base Environment に直接入力、または専用のプロパティとして設定する。
—
5. 実用的な設定ファイル（JSON）のベストプラクティス構成例
Insomniaのワークスペースをエクスポートした際に出力されるJSONファイルの構造を理解しておくことは、CI/CDパイプラインとの統合や自動テスト（Inso CLIの活用）において極めて重要だ。
以下は、保守性を最大限に高めたワークスペース設定の模範的なJSONスニペットである。
{
“_type”: “export”,
“__export_format”: 4,
“__export_date”: “202X-10-24T00:00:00.000Z”,
“__export_source”: “insomnia.desktop.app:v202X.x.x”,
“resources”: [
{
“_id”: “wrk_workspace_root”,
“parentId”: null,
“modified”: 1698115200000,
“created”: 1698115200000,
“name”: “Core Banking API – v1”,
“description”: “コアバッキングシステムのマイクロサービス群検証用ワークスペース”,
“_type”: “workspace”
},
{
“_id”: “env_base_environment”,
“parentId”: “wrk_workspace_root”,
“modified”: 1698115200000,
“created”: 1698115200000,
“name”: “Local Development”,
“data”: {
“base_url”: “http://localhost:8080/api/v1”,
“API_SECRET”: “your_local_secret_here_do_not_commit”
},
“dataPropertyOrder”: {
“&”: [
“base_url”,
“API_SECRET”
]
},
“color”: “#7d69cb”,
“isPrivate”: false,
“_type”: “environment”
},
{
“_id”: “req_get_account”,
“parentId”: “fld_accounts_group”,
“modified”: 1698115200000,
“created”: 1698115200000,
“url”: “{{ _.base_url }}/accounts/{{ _.CURRENT_SESSION_ID }}”,
“name”: “Get Account Details”,
“description”: “セッションIDを用いた口座情報取得エンドポイント”,
“method”: “GET”,
“body”: {},
“parameters”: [],
“headers”: [
{
“name”: “Accept”,
“value”: “application/json”
}
],
“authentication”: {},
“metaSortKey”: -1698115200000,
“isPrivate”: false,
“settingStoreCookies”: true,
“settingSendCookies”: true,
“settingDisableRenderPath”: false,
“settingEncodeUrl”: true,
“settingRebuildPath”: true,
“settingFollowRedirects”: “global”,
“_type”: “request”
}
]
}
この構成を維持することで、`inso` CLIを用いたヘッドレスなテスト実行（例: CIパイプライン上での自動APIテスト）への移行も極めてスムーズに行えるようになる。
—
最後に：ツールに流されるな、ツールを支配しろ
APIクライアントは単なる「URLを叩く画面」ではない。ここに紹介したカスタムスクリプトやショートカット、そして構造化された設定ファイルの運用を取り入れることで、あなたの開発チームの生産性は確実に別次元へと到達する。
手作業によるエラーを根絶し、機械的にやれることはすべてInsomniaに肩代わりさせる。その浮いたリソースを、真に価値のあるアーキテクチャ設計やビジネスロジックの実装にブーストさせよう。