DEV Community

Cover image for httpYacとは？
Akira
Akira

Posted on • Originally published at apidog.com

httpYacとは？

httpYacを調べているなら、Gitで管理できるプレーンテキストからHTTPリクエストを送信し、VS Code内で実行し、CIで再実行する方法を探しているはずです。httpYacは、.http / .restファイルをVS Code拡張機能またはNode.js CLIで実行できるHTTPクライアントです。この記事では、httpYacの基本、.httpファイルの書き方、変数・アサーション・CI実行の実装手順、そしてGUIベースのAPI管理が必要になった場合の選択肢を整理します。APIテスト全般を体系的に確認したい場合は、APIテストガイドも参考になります。

今すぐApidogを試す

httpYacとは何か

httpYacは、.httpファイル形式を中心にしたオープンソースのHTTPクライアントです。リクエストをテキストで記述し、VS Codeから直接送信するか、ターミナルでhttpyacコマンドとして実行できます。

プロジェクトはGitHubで公開されており、公式ドキュメントはhttpyac.github.ioにあります。

httpYac CLI

httpYacの基本的な使い方は次の流れです。

  1. APIリクエストを.httpまたは.restファイルに書く
  2. そのファイルをアプリケーションコードと一緒にGitで管理する
  3. VS Codeで開発中に手動実行する
  4. 同じファイルをCIで再実行する

つまり、PostmanコレクションのようなGUI管理ではなく、「リクエストをコードの近くに置く」ワークフローに向いています。

httpYacは主に2つのインターフェースで使います。

  • VS Code拡張機能
    • 各リクエストの上に「Send Request」のコードレンズを表示
    • レスポンスをエディタ内で確認
    • 環境を切り替えて実行
  • CLI
    • npm経由でhttpyacをインストール
    • .httpファイルをヘッドレスで実行
    • CI/CDパイプラインに組み込みやすい

どちらも同じ.httpファイルを読むため、エクスポートや変換の手順は不要です。

.httpファイルの基本形式

.httpファイルでは、###でリクエストを区切ります。各ブロックは、実際のHTTPリクエストに近い形式で記述します。

### Get a user
GET https://api.example.com/users/42
Accept: application/json

### Create a user
# @name createUser
POST https://api.example.com/users
Content-Type: application/json

{
  "name": "Ada Lovelace",
  "email": "ada@example.com"
}

### Use a value from the previous response
GET https://api.example.com/users/{{createUser.response.body.$.id}}
Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

この例で重要なポイントは次の通りです。

  • ###でリクエストを分割する
  • # @name createUserでリクエストに名前を付ける
  • {{...}}で変数や前のレスポンス値を参照する
  • JSONボディやヘッダーをそのまま記述できる

# @nameを付けておくと、後続リクエストからレスポンスを参照できます。たとえば、作成APIのレスポンスに含まれるidを使って、次のGETリクエストを実行できます。

変数と環境を使う

実際のAPIテストでは、ローカル・ステージング・本番などでホスト名や認証情報が変わります。httpYacでは、次のような場所から変数を読み込めます。

  • .env
  • http-client.env.json
  • .httpファイル内のインライン変数
  • CI上の環境変数

まず、.httpファイルに共通変数を定義します。

@host = https://api.staging.example.com

### Login
# @name login
POST {{host}}/auth/login
Content-Type: application/json

{
  "user": "{{USERNAME}}",
  "pass": "{{PASSWORD}}"
}
Enter fullscreen mode Exit fullscreen mode

認証情報などのシークレットは、Gitにコミットしない.envに置きます。

USERNAME=dev-user@example.com
PASSWORD=local-password
Enter fullscreen mode Exit fullscreen mode

.gitignoreには次のように追加しておきます。

.env
Enter fullscreen mode Exit fullscreen mode

CIでは、同じUSERNAMEやPASSWORDをパイプラインのシークレットとして注入します。これにより、.httpファイル自体は安全にGit管理できます。

スクリプトとアサーションを書く

httpYacでは、リクエストにJavaScriptを埋め込んで、レスポンス検証や値の保存ができます。軽量なAPIチェックを作る場合に便利です。

次の例では、ログインAPIのステータスコードを検証し、レスポンスからトークンを取り出しています。

### Login and capture token
# @name login
POST {{host}}/auth/login
Content-Type: application/json

{
  "user": "{{USERNAME}}",
  "pass": "{{PASSWORD}}"
}

{{
  // ポストリクエストスクリプト
  test("status is 200", () => {
    client.assert.strictEqual(response.statusCode, 200);
  });

  exports.token = response.parsedBody.token;
}}
Enter fullscreen mode Exit fullscreen mode

保存したtokenは、後続リクエストで{{token}}として使えます。

### Get current user
GET {{host}}/me
Authorization: Bearer {{token}}
Enter fullscreen mode Exit fullscreen mode

このように、次のような処理を.httpファイル内で完結できます。

  • ステータスコードの検証
  • レスポンスボディの検証
  • 認証トークンの保存
  • 後続リクエストへの値の受け渡し
  • 署名や動的パラメータの生成

本格的なE2Eテストフレームワークを導入するほどではないが、APIの基本チェックをCIに入れたい場合に向いています。

CLIでhttpYacを実行する

CIに組み込むには、まずCLIをインストールします。

npm install -g httpyac
Enter fullscreen mode Exit fullscreen mode

単一ファイルを実行する場合は次の通りです。

httpyac send api/users.http
Enter fullscreen mode Exit fullscreen mode

フォルダ内の複数ファイルをまとめて実行する場合は、--allやglobを使います。

httpyac send --all "api/**/*.http"
Enter fullscreen mode Exit fullscreen mode

環境を指定して実行する場合は、--envを使います。

httpyac send --all --env staging "api/**/*.http"
Enter fullscreen mode Exit fullscreen mode

アサーションが失敗すると、httpYacは非ゼロの終了コードを返します。そのため、CIジョブではそのままビルド失敗として扱えます。

たとえば、GitHub Actionsでは次のように組み込めます。

name: API checks

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  httpyac:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install httpYac
        run: npm install -g httpyac

      - name: Run API checks
        run: httpyac send --all --env staging "api/**/*.http"
        env:
          USERNAME: ${{ secrets.API_USERNAME }}
          PASSWORD: ${{ secrets.API_PASSWORD }}
Enter fullscreen mode Exit fullscreen mode

この構成にすると、ローカルでVS Codeから実行していた.httpファイルを、そのままPull Requestのチェックとして使えます。

httpYacが向いているケース

httpYacは、すべてのチームに最適なツールではありません。特に、開発者中心のGitワークフローに強く合います。

状況 httpYacが適する理由
VS Codeを日常的に使う 拡張機能でリクエストをコードの近くに置ける
APIリクエストをGitで管理したい プレーンテキストなので差分が見やすく、PRレビューしやすい
チームがコードに慣れている .env、スクリプト、CLI実行を自然に扱える
軽量なAPIチェックをCIに入れたい 導入が簡単で、特定のGUIプラットフォームに依存しない
すでにREST Client形式のファイルを使っている 近い形式なので移行しやすい

一方で、次のような場合は別の選択肢を検討した方がよいです。

  • 開発者以外もAPIリクエストを編集・実行する
  • 大量のリクエストを視覚的に整理したい
  • チーム共有の環境変数をGUIで管理したい
  • モックサーバーやAPIドキュメントも同じ場所で扱いたい
  • レポートや負荷テストも含めて統合したい

.httpファイルはシンプルで強力ですが、チームが大きくなるほど、ファイル管理だけでは運用が重くなることがあります。

httpYacとGUI / CIプラットフォームの違い

httpYacは、Git上のテキストファイルを実行するHTTPランナーです。一方、ApidogはGUIファーストのAPIプラットフォームで、CI実行にも対応しています。

重要な違いとして、Apidogは.httpファイルをネイティブに実行・パースするツールではありません。.httpファイル群を真実のソースとして管理したい場合は、httpYacが直接的な選択肢です。

機能 httpYac Apidog
リクエストソース Git内の.http / .restファイル ワークスペース内の視覚的なリクエスト、OpenAPIインポート
編集インターフェース VS Codeまたは任意のテキストエディタ フォームとスキーマ認識を備えたビジュアルビルダー
変数と環境 .env、JSON、インライン変数 チームで共有・管理できる環境
アサーション リクエスト内のJavaScript ビジュアルアサーションとスクリプティング
CI実行 httpyac send apidog run
モックとドキュメント 内蔵されていない モックサーバーと自動生成ドキュメントを利用可能
主な用途 GitネイティブなAPIチェック 設計、テスト、モック、ドキュメントの一元管理

GUIでAPIを整理したい場合、Apidogでは手動で.httpファイルを書くのではなく、ワークスペース上でリクエストやシナリオを構築します。CIではapidog runを使って同じシナリオを実行できます。

詳しいコマンドや環境フラグ、レポーターについては、apidog runリファレンスを確認してください。

また、モックサーバーが主な要件であれば、RESTエンドポイントモックツールの一覧も参考になります。

使い分けの目安

httpYacを選ぶべきなのは、次のような場合です。

  • .httpファイルをGitで管理したい
  • 開発者だけでAPIチェックを運用する
  • VS Code中心で作業している
  • CIで軽量にAPIリクエストを再実行したい
  • リクエスト定義をコードレビューの対象にしたい

Apidogを選ぶべきなのは、次のような場合です。

  • GUIでAPIリクエストを設計・整理したい
  • 開発者以外もAPI仕様やテストに関わる
  • チーム共有の環境管理が必要
  • モック、ドキュメント、テストを同じ場所で扱いたい
  • CI実行とレポートをAPI管理ワークフローに統合したい

一部のチームでは、httpYacをローカルの軽量チェックに使い、Apidogをチーム全体のAPIワークスペースとして使う構成もあります。

結論として、httpYacは「Git内のファイルを、エディタとCIでそのまま実行する」ワークフローに最適です。チームでAPI設計、テスト、モック、ドキュメントまでまとめて管理したい場合は、GUIベースのプラットフォームを検討するとよいでしょう。

Top comments (0)