httpYacとは？

httpYacを検索された方は、おそらくGitで管理できるプレーンテキストファイルからHTTPリクエストを送信し、VS Code内で実行し、CIでリプレイする方法を求めていることでしょう。httpYacはまさにそれであり、VS Code拡張機能とNode.jsコマンドラインツールの両方として提供される.http/.restファイルランナーです。このガイドでは、その仕組み、簡単な例、適した場面、そしてテキストファイルでは物足りなくなった場合のGUIとCIのパスについて説明します。この分野に関するより広範な知識については、弊社のAPIテストガイドをご覧ください。

ボタン

httpYacとは一体何か

httpYacは、.httpファイル形式を中心に構築されたオープンソースのHTTPクライアントです。リクエストをプレーンテキストで記述し、エディタでキー操作一つ、またはターミナルで単一のコマンドで送信できます。このプロジェクトはGitHubで公開されており、完全なドキュメントはhttpyac.github.ioにあります。

核となるアイデアはシンプルです。リクエストはコードの隣にあるテキストファイルに記述されます。それをGitでバージョン管理し、プルリクエストでレビューします。エディタを使う人間であろうと、ビルドサーバー上のCIジョブであろうと、同じ方法で実行できます。このGitネイティブなプレーンテキストモデルこそがhttpYacの最大の強みであり、多くのバックエンド開発者がこれを利用する理由です。

このツールは2つの部分で構成されています。

VS Code拡張機能 (httpYac) は、各リクエストの上に「リクエストを送信」コードレンズ、レスポンスプレビュー、エディタ内での環境切り替え機能を提供します。
CLI (httpyac、npm経由でインストール) は、同じファイルをヘッドレスで実行します。これによりCIフレンドリーになり、ローカルでテストしたファイルがパイプラインで実行されます。

両方のインターフェースが同じ.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}}

ここにはいくつかの要素があります。###の行はリクエストを分割します。# @nameコメントは、後でそのレスポンスを参照できるようにリクエストに名前を付けます。{{...}}プレースホルダーは、以前のレスポンスから連鎖的に取得された値を含む変数を取り込みます。この形式は一般的なREST Client拡張機能と共有されているため、ファイルは軽微な修正で両者間を移動することがよくあります。

変数と環境

httpYacは、.envファイル、http-client.env.jsonファイル、およびリクエストファイル内のインライン定義から変数を読み込みます。ローカル用、ステージング用、本番用の一連の値を保持し、リクエストを編集することなくそれらを切り替えることができます。

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

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

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

シークレットはGitから除外する.envファイルに保持されるため、リクエストファイル自体は安全にコミットできます。CIでは、同じ変数が環境変数またはパイプラインシークレットから提供されます。

スクリプティングとアサーション

これは、httpYacが基本的なリクエスト送信機能を超えている部分です。JavaScriptをリクエストに埋め込んで、実行前にデータをセットアップしたり、実行後にレスポンスをチェックしたりできます。プリリクエストおよびポストリクエストブロックはNodeコンテキストで実行されるため、署名を計算したり、トークンを保存したり、ボディに対してアサートしたりできます。

### 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;
}}

キャプチャされたtokenは、次のリクエストで{{token}}として利用可能になります。スクリプティングモデルは柔軟であり、完全なテストフレームワークを立ち上げることなくロジックを実行したい開発者にとって魅力の一部です。

CIでのhttpYacの実行

CLIは、「自分のマシンでは動く」から「パイプラインで動く」への橋渡しとなります。これをインストールし、ファイルを指定するだけです。

npm install -g httpyac

# 単一ファイルを実行
httpyac send api/users.http

# フォルダ内のすべてのリクエストを実行し、環境を選択し、アサーションエラーで失敗する
httpyac send --all --env staging "api/**/*.http"

アサーションが失敗するとhttpYacはゼロ以外のコードで終了します。これはCIジョブがビルドを失敗とマークするために必要な挙動です。JUnit形式の出力をテストレポーター向けに生成できるため、結果はログに埋もれることなくCIダッシュボードに表示されます。このコマンドをGitHub Actions、GitLab CI、またはJenkinsに組み込めば、VS Codeで編集したのと同じファイルがマージをゲートするようになります。

httpYacを使うべき時

httpYacは特定のチームとワークフローの形に適合します。以下のほとんどが当てはまる場合に利用を検討してください。

状況	httpYacが適する理由
VS Codeを日常的に使う	拡張機能によりリクエストがコードの隣に置かれ、コンテキスト切り替えが不要
Gitでリクエストを管理したい	プレーンテキストはきれいに差分が取れ、PRでレビューできる
チームがコードに慣れている	スクリプティングと`.env`ファイルは開発者の一定の熟練度を前提とする
少数の集中したチェックを実行する	軽量で導入が容易、特定のプラットフォームを採用する必要がない
すでにREST Clientファイルを使用している	共通のフォーマットなので移行が簡単

開発者以外がリクエストを実行または編集する必要がある場合、大規模なリクエストコレクションを視覚的に確認したい場合、ファイルを設定することなく共有環境とチーム同期が必要な場合、またはよりリッチなレポート作成と負荷テストを1箇所で行いたい場合には、あまり適しません。スイートが大規模になりチームが拡大すると、プレーンテキストの使いやすさは特徴となります。

httpYac vs GUIおよびCIプラットフォーム

httpYacはテキストファイルランナーです。Apidogは異なるモデルであり、CIでも実行できるGUIファーストのAPIプラットフォームです。どちらも抽象的には「より優れている」というものではなく、問題を正反対の視点から解決します。まず明確にしておくべき点が一つあります。Apidogはネイティブに.httpファイルを実行またはパースしません。もし真実の源が.httpファイルのフォルダであるならば、httpYacはそれらを直接実行します。これこそがhttpYacの本質的な強みです。

選択を決定する要素で両者を比較したのが次の表です。

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

視覚的な側面を重視するなら、Apidogは手動でファイルを記述することなくリクエストを構築・整理し、apidog runでCIで同じシナリオを実行できます。apidog runリファレンスでは、コマンド、環境フラグ、レポーターについて解説しています。また、同じワークスペース内でモックサーバーとドキュメントも利用できますが、これはテキストファイルランナーが他のツールに任せる部分です。モックが真のニーズである場合、弊社のRESTエンドポイントモックツールの一覧で選択肢を網羅しています。

率直なまとめ：httpYacは、全体のワークフローが「Git内のファイル、エディタで実行、CIでリプレイ」であり、チームが全員開発者である場合に優れています。Apidogは、共有のビジュアルワークスペース、管理された環境、モック、およびCI実行と連携するドキュメントが必要な場合に優れています。一部のチームでは、httpYacを簡単なローカルチェックに使い、Apidogをチームの真実の源として、両方を使用することもあります。チームの働き方に合ったモデルを選んでください。

ボタン