Insomniaの使い方完全ガイド【インストールから応用まで】

API開発者は日々、外部サービス連携や自社APIの開発に奮闘しています。しかし、APIリクエストのテストは多くの手間がかかる作業です。

例えば、ターミナルでcURLコマンドを手打ちする作業を想像してください。複雑なJSONボディを手作業で整形し、認証ヘッダーを毎回入力します。環境が変わるたびにURLを書き換えるのも一苦労です。

また、チームメンバーとAPI仕様を共有し、同じ環境でテストを行うのも簡単ではありません。これらの課題は、開発効率を大きく低下させる要因となります。

Insomniaがあれば、これらの課題は解決します。直感的なGUIでリクエストを作成し、環境を簡単に切り替えられます。チームメンバーとの共有もスムーズに行え、API開発とテストのプロセスを劇的に改善します。

この記事では、Insomniaの基本的な使い方から、開発現場で役立つ応用テクニックまでを詳しく解説します。

Insomniaとは

Insomniaは、REST、GraphQL、WebSocketなど多様なプロトコルに対応したオープンソースのAPIクライアントです。APIのデバッグ、設計、テスト、モック作成、CI/CD連携までを一貫してサポートします。

特に、使いやすいグラフィカルユーザーインターフェース（GUI）が特徴です。これにより、複雑なAPIリクエストも直感的に作成し、結果を分かりやすく確認できます。

Insomniaは、2016年にOpenAPIエコシステムに貢献するために開発が始まりました。その後、APIゲートウェイのKong社に買収され、オープンソースプロジェクトとして活発に開発が続けられています。

個人のAPI開発から、チームでの大規模開発まで、幅広いシーンで活用できる強力なツールです。プロジェクトの保存方法も柔軟で、ローカル、Gitリポジトリ、クラウドの中から選択できます。

インストール方法

InsomniaはmacOS、Linux、Windowsの主要なOSに対応しています。ここでは、各OSでのインストール方法を説明します。

最も簡単な方法は、公式サイトからインストーラーをダウンロードすることです。

https://insomnia.rest

macOS

macOSでは、Homebrew Caskを利用してインストールできます。

brew install --cask insomnia

Linux

Linuxでは、Snapストアからインストールする方法が一般的です。

sudo snap install insomnia

または、AppImageファイルをダウンロードして実行することも可能です。AppImageは、インストール不要でアプリケーションを実行できる形式です。

1. Insomniaの公式サイトから .AppImage ファイルをダウンロードします。
2. ダウンロードしたファイルに実行権限を付与します。

   chmod +x Insomnia*.AppImage
   

3. ファイルを実行します。

   ./Insomnia*.AppImage
   

Windows

Windowsでは、公式サイトからインストーラー（.exe ファイル）をダウンロードして実行するのが最も簡単です。

また、Winget（Windows Package Manager）を利用してインストールすることも可能です。

winget install Kong.Insomnia

インストールが完了したら、アプリケーションを起動してください。初回起動時には、アカウントの作成またはScratch Padでの利用を選択できます。Scratch Padは、ローカルのみで利用する際に便利です。

基本的な使い方

ここでは、Insomniaを使ってAPIリクエストを送信し、レスポンスを確認する基本的な手順を説明します。最低限これだけ知っていれば、すぐにAPIのテストを開始できます。

1. 新規リクエストの作成

Insomniaを起動すると、左側のサイドバーに「Documents」セクションがあります。ここにAPIリクエストを整理して保存できます。

まず、新しいリクエストを作成しましょう。サイドバーの「+」ボタンをクリックし、「New Request」を選択します。

（スクリーンショットは公式READMEのメイン画像を使用しています。実際のUIは異なる場合があります。）

リクエスト名を入力し、リクエストメソッド（GET、POSTなど）を選択して「Create」をクリックします。

2. GETリクエストの送信

シンプルなGETリクエストを試してみましょう。例えば、公開されているJSONPlaceholder APIを利用します。

1. リクエストメソッドを GET に設定します。
2. URL入力欄に https://jsonplaceholder.typicode.com/todos/1 と入力します。
3. 「Send」ボタンをクリックします。

# InsomniaのGUI操作の例
# 1. New Requestを作成し、MethodをGETに設定
# 2. URLフィールドに https://jsonplaceholder.typicode.com/todos/1 を入力
# 3. Sendボタンをクリック

レスポンスが右側のペインに表示されます。ステータスコード、ボディ、ヘッダーなどが確認できます。

3. POSTリクエストとJSONボディの送信

次に、データを作成するPOSTリクエストを試します。

1. 新しいリクエストを作成し、メソッドを POST に設定します。

2. URL入力欄に https://jsonplaceholder.typicode.com/posts と入力します。

3. 「Body」タブを選択し、ドロップダウンから「JSON」を選択します。

4. テキストエリアに以下のJSONデータを入力します。

   {
     "title": "Insomnia Tutorial",
     "body": "This is a test post from Insomnia.",
     "userId": 1
   }
   

5. 「Send」ボタンをクリックします。

# InsomniaのGUI操作の例
# 1. New Requestを作成し、MethodをPOSTに設定
# 2. URLフィールドに https://jsonplaceholder.typicode.com/posts を入力
# 3. Bodyタブを選択し、JSON形式を選択
# 4. 上記のJSONデータを入力
# 5. Sendボタンをクリック

レスポンスとして、作成されたリソースの情報（id など）が返されます。

4. ヘッダーの追加

APIによっては、認証情報やコンテンツタイプをヘッダーで指定する必要があります。

1. リクエスト編集画面で「Headers」タブを選択します。
2. 「Add Header」ボタンをクリックし、Content-Type と入力します。
3. 値のフィールドに application/json と入力します。
4. 同様に、例えば認証トークンを追加する場合は Authorization ヘッダーを追加します。

# InsomniaのGUI操作の例
# 1. Headersタブを選択
# 2. Add Headerボタンをクリック
# 3. Key: Content-Type, Value: application/json
# 4. Key: Authorization, Value: Bearer your_auth_token_here

これらの基本的な操作をマスターすれば、ほとんどのAPIテストを開始できます。

便利な使い方・応用例 3選

Insomniaには、API開発をさらに効率化するための便利な機能が多数あります。ここでは、実際の開発シーンで役立つ応用例を3つ紹介します。

1. 環境変数による環境管理

開発、ステージング、本番など、複数の環境でAPIをテストする場合、URLや認証情報が環境ごとに異なります。Insomniaの環境変数機能を使えば、これらの情報を簡単に切り替えられます。

設定方法

1. 左側のサイドバー上部にある「No Environment」または現在の環境名をクリックします。

2. 「Manage Environments」を選択します。

3. 「New Environment」をクリックして、例えば「Development」という環境を作成します。

4. 環境設定のJSONエディタに、環境固有の変数を定義します。

   {
     "base_url": "https://dev.api.example.com",
     "api_key": "dev_api_key_123",
     "auth_token": "bearer dev_jwt_token"
   }
   

5. 同様に「Production」環境も作成し、異なるURLやキーを設定します。

   {
     "base_url": "https://prod.api.example.com",
     "api_key": "prod_api_key_456",
     "auth_token": "bearer prod_jwt_token"
   }
   

使用方法

リクエストのURLやヘッダーで、{{ 環境変数名 }} の形式で変数を参照します。Insomniaは自動的に補完候補を表示します。

例えば、URLを {{ base_url }}/users とし、ヘッダーに Authorization: {{ auth_token }} と設定します。

# InsomniaのGUI操作の例
# 1. URLフィールドに {{ base_url }}/users と入力
# 2. HeadersタブでAuthorizationヘッダーを追加し、値に {{ auth_token }} と入力
# 3. サイドバー上部の環境セレクタから「Development」または「Production」を選択して切り替える

環境を切り替えるだけで、リクエストのURLや認証情報が自動的に更新されます。これにより、環境ごとの設定変更の手間が大幅に削減されます。

2. テストスイートとコレクションランナーによるAPIテスト自動化

Insomniaは、APIのレスポンスを検証するテストを記述できます。さらに、複数のリクエストとテストをまとめて実行するコレクションランナー機能も備えています。これは、APIの回帰テストやCI/CDパイプラインへの組み込みに非常に役立ちます。

テストの記述

1. リクエスト編集画面で「Tests」タブを選択します。

2. JavaScriptを使ってテストスクリプトを記述します。expect 関数を使用してアサーションを行います。

   const response = await insomnia.send(); // リクエストを送信し、レスポンスを取得
   
   // ステータスコードが200であることを確認
   expect(response.status).to.equal(200);
   
   // レスポンスボディに特定のプロパティが存在することを確認
   expect(response.data).to.have.property('id');
   expect(response.data.id).to.be.a('number');
   
   // 特定のプロパティの値が期待通りであることを確認
   expect(response.data.title).to.equal('Insomnia Tutorial');
   
   // レスポンスから次のリクエストに渡す値を環境変数に保存
   insomnia.setEnvironmentVariable('new_post_id', response.data.id);
   

コレクションランナーの利用

1. 左側のサイドバーでコレクション（フォルダ）を右クリックし、「Collection Runner」を選択します。
2. テストを実行したいリクエストを選択します。
3. 「Run Tests」ボタンをクリックします。

Insomniaは選択されたリクエストを順番に実行し、各リクエストに紐づけられたテストの結果を表示します。これにより、一連のAPIフローが正しく動作するかを自動的に検証できます。

CI/CD連携 (inso CLI)

Insomniaには inso というCLIツールが付属しています。これを使えば、ターミナルやCI/CDパイプラインからInsomniaのテストを実行できます。

まず、inso CLIをインストールします。npmが利用できます。

npm install -g @getinsomnia/inso

プロジェクトをエクスポートし、そのパスを指定してテストを実行します。

# コレクション（例: MyAPICollection）をエクスポート
# GUIでプロジェクトをエクスポートする。またはGit Syncを利用。

# エクスポートしたファイル（例: insomnia_export.json）を使ってテストを実行
inso run test "MyAPICollection" --env "Development" --ci

--ci オプションを付けると、CI/CD環境で利用しやすいシンプルな出力が得られます。これにより、GitHub ActionsやGitLab CI/CDなどのCI/CDツールにAPIテストを組み込み、デプロイ前に自動でAPIの健全性をチェックできます。

3. Git Syncによるチーム開発とバージョン管理

APIリクエストのコレクションは、チーム開発において重要な資産です。InsomniaのGit Sync機能を使えば、コレクションをGitリポジトリで管理し、チームメンバーと共有できます。

設定方法

1. Insomniaのアプリケーション内で、左上のワークスペース名をクリックします。
2. 「Create / Import Document」または既存のドキュメントを選択します。
3. ストレージオプションで「Git Sync」を選択します。
4. GitリポジトリのURL、ブランチ名、認証情報（パーソナルアクセストークンなど）を設定します。

チームでの利用

コレクションがGitリポジトリに同期されると、チームメンバーは同じリポジトリをクローンし、Insomniaで開くことで同じAPIリクエスト環境を共有できます。

• バージョン管理: リクエストの変更履歴がGitで管理されるため、いつ誰が何を変更したか追跡できます。
• 競合解決: 複数のメンバーが同時に変更した場合でも、Gitの機能を使って競合を解決できます。
• レビュー: プルリクエストを通じて、APIリクエストの変更内容をレビューできます。

これにより、APIテストの資産をチーム全体で一元的に管理し、共同で開発を進めることが容易になります。

他ツールとの組み合わせ

Insomniaは単体でも強力ですが、他のツールと組み合わせることで、API開発ワークフロー全体をさらに強化できます。

1. OpenAPI Specification (OAS) / Swagger UI

OpenAPI Specification（旧Swagger）は、RESTful APIを記述するための標準フォーマットです。InsomniaはOASをネイティブでサポートしています。

• APIデザイン: InsomniaのNative OpenAPI editorでAPIの仕様を記述し、その場でプレビューを確認できます。これにより、API設計とテストを密接に連携させられます。
• 仕様からのリクエスト生成: 既存のOASファイルをInsomniaにインポートすると、その仕様に基づいて自動的にリクエストコレクションが生成されます。手動でリクエストを作成する手間を省けます。
• ドキュメント生成: Insomniaで作成したOASファイルをエクスポートし、Swagger UIなどのツールで美しいAPIドキュメントを生成できます。

この連携により、API設計から開発、テスト、ドキュメント化までの一貫したフローを構築できます。

2. CI/CDツール (GitHub Actions, GitLab CI/CD)

前述の inso CLIツールは、CI/CDパイプラインとの相性が抜群です。

• 自動テスト: コードがコミットされるたびに、または定期的に、Insomniaで定義したAPIテストをCI/CDパイプラインで自動実行できます。
• 品質保証: APIの変更が既存の機能に影響を与えていないか、新しいAPIが期待通りに動作するかを継続的に検証し、APIの品質を高く保てます。

例えば、GitHub Actionsのワークフローで以下のように inso CLIを呼び出すことができます。

name: API Tests with Insomnia

on: [push, pull_request]

jobs:
  run-insomnia-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Install inso CLI
        run: npm install -g @getinsomnia/inso

      - name: Run Insomnia tests
        # ここでは、プロジェクトルートにエクスポートされたコレクションファイルがあると仮定
        # または、Git Syncでリポジトリに同期されているコレクション名を指定
        run: inso run test "My API Project" --env "Development" --ci
        env:
          INSOMNIA_API_KEY: ${{ secrets.INSOMNIA_API_KEY }} # 必要であればAPIキーを設定

3. Docker

Dockerは、アプリケーションとその依存関係をコンテナとしてパッケージ化するツールです。API開発環境の構築によく利用されます。

• ローカル開発環境: Docker Composeなどを使ってローカルでAPIサーバーを立ち上げ、InsomniaからそのAPIに対してリクエストを送信し、テストを行う開発フローが一般的です。
• 一貫性: チーム全員がDockerで同じAPI環境を構築できるため、環境差異による問題を防ぎ、Insomniaでのテストも一貫性を持って実施できます。

例えば、Dockerコンテナで立ち上げたAPIの localhost アドレスに対してInsomniaからリクエストを送ることで、開発中のAPIをリアルタイムでデバッグできます。

よくある設定・カスタマイズ

Insomniaは、ユーザーの好みに合わせて様々な設定やカスタマイズが可能です。dotfilesのような設定ファイルは直接操作しませんが、GUIを通じて多くのオプションを変更できます。

1. テーマの変更

Insomniaは、ダークテーマやライトテーマ、その他多くのカスタムテーマをサポートしています。

1. 左上部の「Insomnia」メニュー（macOS）または「File」メニュー（Windows/Linux）から「Preferences」を選択します。
2. 「Themes」タブで、好みのテーマを選択します。

2. プラグインの導入

Insomniaは、3rdパーティのプラグインによって機能を拡張できます。例えば、カスタム認証ヘルパーやスクリプト実行機能などがあります。

1. 「Preferences」の「Plugins」タブを選択します。
2. 「Install Plugin」ボタンをクリックし、プラグインの名前を入力してインストールします。
   • 例えば、insomnia-plugin-random-data をインストールすると、ランダムなテストデータを生成するテンプレートタグが利用できるようになります。

3. キーボードショートカットのカスタマイズ

頻繁に使う操作にカスタムショートカットを設定することで、作業効率を向上させられます。

1. 「Preferences」の「Keyboard Shortcuts」タブを選択します。
2. 既存のショートカットを変更したり、新しいショートカットを追加したりできます。

4. プロキシ設定

企業ネットワークなど、プロキシサーバー経由でインターネットに接続する必要がある場合、Insomniaのプロキシ設定が役立ちます。

1. 「Preferences」の「Network」タブを選択します。
2. 「Proxy」セクションで、プロキシサーバーのアドレス、ポート、認証情報などを設定します。

これらの設定やカスタマイズを通じて、Insomniaをより快適に、そして効率的に利用できます。

今日からできる実行プラン

Insomniaの導入は非常に簡単です。以下の3ステップで、今日からAPIテストを始めましょう。

ステップ1: Insomniaをインストールする

まず、利用しているOSに対応したInsomniaをインストールします。公式サイトからダウンロードするか、HomebrewやSnapなどのパッケージマネージャーを利用するとスムーズです。

# macOSの場合
brew install --cask insomnia

# Windowsの場合
winget install Kong.Insomnia

インストール後、Insomniaを起動し、必要であればKongアカウントを作成します。Scratch Padから始めることも可能です。

ステップ2: シンプルなGETリクエストを試す

アプリケーションが起動したら、新しいリクエストを作成し、公開されているAPIエンドポイントにGETリクエストを送信してみましょう。

例えば、以下のURLを試してみてください。

# Insomniaで新しいGETリクエストを作成し、URLに以下を入力
https://jsonplaceholder.typicode.com/todos/1

「Send」ボタンをクリックすると、右側のペインにレスポンスが表示されます。ステータスコードが 200 OK であれば成功です。

ステップ3: 環境変数を使ってみる

次に、APIテストをより柔軟にするために環境変数を使ってみましょう。

1. 左側のサイドバー上部の「No Environment」をクリックし、「Manage Environments」を選択します。

2. 「New Environment」をクリックして「Development」という名前の環境を作成します。

3. 環境設定のJSONエディタに、以下の内容を追加します。

   {
     "base_url": "https://jsonplaceholder.typicode.com"
   }
   

4. 先ほど作成したリクエストのURLを {{ base_url }}/todos/1 に変更します。

5. 再度「Send」ボタンをクリックし、同じレスポンスが返ってくることを確認します。

これで、環境変数の基本的な使い方をマスターしました。この機能は、複数のAPIエンドポイントや認証情報を環境ごとに管理する際に非常に役立ちます。

Insomniaを使いこなせば、API開発とテストの効率が格段に向上します。ぜひ今日からInsomniaを活用し、快適なAPI開発ライフを送りましょう。

参考文献

• Insomnia REST Client Best Practices
• Automating API Tests with Insomnia and GitHub Actions
• [Debug and Test GraphQL APIs with Insomnia](https://blog.insomnia.rest/debug-and-test-graphql-apis-with-insomnia