Insomniaとは — 開発におけるREST・GraphQLクライアント

Insomniaとは何かと主な特徴

Insomnia は、HTTPリクエストの送信とAPIのデバッグのためのクロスプラットフォームアプリケーション（Electron）です。速度とプライバシーを重視したPostmanの代替として、2016年からKong社によって開発されています。データはローカルに保存され、クラウド同期はオプションであり登録が必要です。

インターフェースとナビゲーション

メインウィンドウは3つのカラムに分かれています。左側がリクエストツリー（Workspace）、中央がParams・Headers・Bodyタブ付きのリクエストエディター、右側がPretty・Raw・Previewモード付きのレスポンスパネルです。ダークテーマがデフォルトで有効になっており、CSS変数によるカスタムテーマがサポートされています。

コード生成

Insomniaは、リクエストを20以上の言語とフレームワークのコードにエクスポートできます: cURL、HTTPie、Python Requests、JavaScript Fetch/Axios、Kotlin OkHttp、Swift URLSession、Java Unirest、Ruby Net::HTTPなど。ジェネレーターはヘッダー、リクエストボディ、認証タイプを考慮するため、アプリケーションコードへのAPI統合が高速化されます。

Insomnia vs Postman: APIクライアントの比較

Insomnia とPostmanは同じタスクを解決しますが、優先順位が異なります。Insomniaはより軽量で（約80 MB対約300 MB）、起動が速く、登録を強制されずに完全にオフラインで動作します。Postmanは、モニタリング、モックサーバー、チームワークスペースを備えたより成熟したエコシステムを提供します。

タスクに応じたツールの選択

個人開発やエンドポイントの迅速なテストには、Insomnia のほうが軽量で登録不要のため便利です。共有コレクション、CI/CD統合、本番APIのモニタリングを伴うチーム作業では、Postmanが業界標準であり続けています。

ワークスペースと環境の整理

Insomniaのワークスペースには、フォルダーに分割されたリクエストツリーが含まれます。各リクエストはHTTP、GraphQL、WebSocket、gRPCのいずれかのタイプにできます。ドラッグ＆ドロップ、複製、カラーラベルによるリクエストのグループ化がサポートされています。ワークスペースの設定ファイルはJSON形式で保存されます。

継承を伴う環境変数

Insomniaは、親の変数を継承するネストされた環境（Sub Environments）をサポートします。これにより、グローバル環境でベースURLを定義し、環境ごとに異なるパラメータだけを上書きできます。変数は構文 {`{`}_variable${`}`} で置き換えられます。

// Insomnia環境構造の例
{
    "base_url": "https://api.example.com",
    "timeout": 5000,
    "headers": {
        "Content-Type": "application/json",
        "Accept": "application/json"
    }
}

InsomniaでのGraphQLの利用

Insomnia は、APIクライアントの中でも最高クラスのGraphQLエディターを提供します。GraphQL Queryタブでは、読み込まれたスキーマに基づいてフィールドのオートコンプリート付きでクエリを記述できます。右側には、型・フィールド・引数に関するドキュメントがリアルタイムで表示されます。

スキーマの読み込みとIntrospection

スキーマは、エンドポイントへのGraphQL Introspectionリクエストを通じて読み込まれます。Insomniaはスキーマをローカルにキャッシュし、変更時に自動的に更新します。読み込み後、オートコンプリート（Ctrl+Space）、リクエストの検証、送信前のエラー予測が利用可能になります。

# Insomniaでの変数付きGraphQLクエリ
query GetUser($id: ID!) {
    user(id: $id) {
        name
        email
        posts {
            title
            createdAt
        }
    }
}

プラグインと機能の拡張

Insomnia Plugin Hub には、クライアントの機能を拡張する100以上のプラグインがあります。プラグインは、Preferences → Pluginsメニューから、またはnpm経由で手動でインストールします。人気のカテゴリには、テストデータ生成、さまざまな形式へのエクスポート、カスタムレスポンスバリデータが含まれます。各プラグインは、公開開発者ハブに公開される前に必須のモデレーションを受けます。

人気のプラグイン

• insomnia-plugin-faker — テストリクエスト用のダミーデータ（名前、メール、電話）の生成。
• insomnia-plugin-aws4 — Amazon API GatewayとS3で作業するためのAWS Signature Version 4によるリクエスト署名。
• insomnia-plugin-utils — リクエスト内で直接、日付、ハッシュ化、Base64エンコードを扱うためのユーティリティ。

プラグインはJavaScriptで書かれ、テンプレート化API（response.*、request.*、environment.*）を通じてInsomniaと対話します。プラグインの開発にはNode.jsの基礎知識と、insomnia-pluginタグ付きのnpmパッケージでの公開が必要です。

CLIとテスト自動化

Inso CLI は、ターミナルからリクエストとテストを実行するためのInsomniaに組み込まれたコンソールユーティリティです。Insoは個別のリクエストやコレクション全体を実行し、結果をJSONにエクスポートし、CI/CDパイプラインに統合できます。inso run collection コマンドは、コレクション内のすべてのリクエストを順次実行します。

GitHub Actionsでの統合例

Inso CLIはDockerコンテナとヘッドレスモードで動作するため、GitHub ActionsやGitLab CIで使用できます。起動設定は、エクスポートされたコレクションと環境へのパスを指定してYAMLファイルに記述されます。JavaScriptスクリプトによるステータスコードとレスポンスボディへのアサーションがサポートされています。

# Inso CLIを使用したGitHub Actionsワークフロー
- name: Run API tests
  run: npx insomnia-inso run collection
    --collection "Auth API"
    --env "Staging"
    --reporter junit
    --output reports/api-results.xml

InsomniaとGitの統合およびチーム作業

Insomnia は、Gitによるコレクションの同期をサポートします。コレクションファイルはJSON形式で保存され、プロジェクトのリポジトリに追加できます。Insomniaには、変更の表示、コミットの作成、インターフェースから直接のマージ競合の解決を行うための組み込みのGitクライアントがあります。

Git同期の設定

Gitを接続するには、リポジトリのあるローカルフォルダーを作成し、Insomniaの設定でルートディレクトリとして指定します。アプリケーションはコレクションファイルの変更を自動的に追跡し、Version Controlパネルに表示します。commit、push、pull、バージョン間のdiff表示などの標準操作がサポートされています。

Insomnia Cloudによるチーム作業

Gitを使わないプロジェクトでは、InsomniaはInsomnia Cloudによるクラウド同期を提供します。無料プランには、チームメンバー3人までとコレクションの自動バックアップが含まれます。有料プランでは、アクセス管理、変更監査、優先サポートが追加されます。

Design Modeと仕様書の生成

InsomniaのDesign Modeでは、OpenAPI 3.0形式でAPI仕様書を作成できます。このモードはビジュアルエディターとして機能します。YAMLを手書きせずにエンドポイントとデータスキーマを定義します。仕様書はJSONまたはYAMLにエクスポートできます。

OpenAPIからのコレクション生成

InsomniaはOpenAPI仕様書をインポートし、各エンドポイントのリクエストコレクションを作成します。パスとスキーマは、既製のHTTPリクエストに変換されます。この機能は、仕様書がチームの別のリポジトリに保存されるマイクロサービスとの統合に役立ちます。

リクエストのタグ付け

各リクエストにはカラーラベルを割り当てられます: red、blue、green、orange、purple。タグによるフィルタリングは、フォルダー構造に関係なく検索バーで機能し、数百のエンドポイントと多数のモジュールがあるプロジェクトでのナビゲーションを簡素化します。

Design Modeと仕様書の生成

InsomniaのDesign Modeでは、アプリケーション内で直接OpenAPI 3.0形式のAPI仕様書を作成できます。このモードはビジュアルエディターとして機能します。YAMLを手書きせずにエンドポイント、データスキーマ、パラメータを定義します。仕様書は、リポジトリへの公開用にJSONまたはYAMLへエクスポートできます。

OpenAPIからのコレクション生成

Insomniaは既存のOpenAPI仕様書をインポートし、各エンドポイントのリクエストコレクションを自動的に作成します。パスとスキーマは、正しいデータ型を持つ既製のHTTPリクエストに変換されます。この機能は、仕様書が別のバックエンド開発チームによって保存・保守されるマイクロサービスとの統合に役立ちます。

リクエストのタグ付けとフィルタリング

多数のリクエストを整理するため、Insomniaはタグ付けをサポートします — 各リクエストにはカラーラベルを割り当てられます: red、blue、green、orange、purple。タグによるフィルタリングは、フォルダー構造に関係なく検索バーで機能し、数百のエンドポイントと多数の機能的なAPIモジュールがあるプロジェクトでのナビゲーションを簡素化します。