Resterm

ターミナル向けのAPI-as-codeワークベンチ。

_{トレースとタイムライン表示}

Restermは、リクエストをプレーンな.httpおよび.restファイルに保存するAPIクライアントです。これらのファイルは、他のコードと同じようにリポジトリ内に並べて置くことができます。ターミナルUIを使用するか、CIで同じファイルをresterm runで実行できます。

クイックリンク: スクリーンショット、インストール、クイックスタート、リクエストファイル、ドキュメント。

スクリーンショット

Restermを選ぶ理由

• HTTP、GraphQL、gRPC、WebSocket、SSEをサポート。
• リクエストファイル内での自動化: 条件(@when、@if/@elif/@else、@for-each)、マルチステップワークフロー(@workflow / @step)、キャプチャ、変数、アサーション(@capture、@var、@assert)。
• リクエストファイル内のトンネル: @sshと@k8sは、Restermが自動で開閉するSSH踏み台またはKubernetesポートフォワードを経由してリクエストをルーティングします。ファイル単位またはワークスペース単位のプロファイルに対応。
• HTTPトラフィックの記録と、リクエストまたはモックレスポンスとしてRestermの.httpファイルへのエクスポート。
• RestermScript — Restermのために作られた小さな式言語。必要に応じてJavaScriptフックも利用可能。
• Vimライクな操作 — ショートカットヒント、検索可能なオフラインヘルプ、カーソル下のヘルプを表示するShift+k、/検索、:w、:q、:help、:docsなどのコマンド。
• 認証: OAuth 2.0(クライアントクレデンシャル、パスワード、PKCE付き認可コード)と、gh auth tokenのように既にインストール済みのCLIからトークンを再利用する@auth command。
• CLIランナー: スクリプト実行とCI向けのresterm run。JSONおよびJUnit出力に対応。
• モックサーバー — 模倣するリクエストの隣に宣言でき、マッチングルール、シーケンス、呼び出し検証、ホットリロードを備える。
• タイムライントレース、プロファイリング、環境間の実行比較。
• ストリーミングトランスクリプトと、WebSocketおよびSSE用のインタラクティブコンソール。
• AI統合なし

インストール

macOSおよびLinux:

brew install resterm
# or
curl -fsSL https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.sh | bash

Windows:

iwr -useb https://raw.githubusercontent.com/unkn0wn-root/resterm/main/install.ps1 | iex

Go 1.25以降を使ったソースからのインストール:

go install github.com/unkn0wn-root/resterm/cmd/resterm@latest

[!IMPORTANT] ビルド済みのLinuxバイナリはglibc 2.32以降に依存します。古いディストリビューションでは、新しいglibcツールチェーンでソースからビルドするか、リリースアーカイブを使用する前にglibcをアップグレードしてください。

Homebrewでのインストールはbrew upgrade restermで更新されます。リリースページまたはインストールスクリプトから取得したバイナリは、resterm --check-updateとresterm --updateを使用します。これらはダウンロード、検証、その場でのインストールを行います。Windowsでは古いバイナリはresterm.exe.oldとして新しいバイナリの隣に残り、次回の更新時にクリーンアップされます。

手動インストール

macOS、Linux、Windows(amd64およびarm64)用のバイナリはリリースページにあります。以下のコマンドは、リリースページから手動でダウンロードするのと同じことを行います。Unix版にはcurlとjqが必要です。

# Find the latest release tag
LATEST_TAG=$(curl -fsSL https://api.github.com/repos/unkn0wn-root/resterm/releases/latest | jq -r .tag_name)

# Download the matching binary (Darwin/Linux + amd64/arm64)
curl -fL -o resterm "https://github.com/unkn0wn-root/resterm/releases/download/${LATEST_TAG}/resterm_$(uname -s)_$(uname -m)"

# Install on PATH
chmod +x resterm
sudo install -m 0755 resterm /usr/local/bin/resterm

$latest = Invoke-RestMethod https://api.github.com/repos/unkn0wn-root/resterm/releases/latest
$asset  = $latest.assets | Where-Object { $_.name -like 'resterm_Windows_*' } | Select-Object -First 1
Invoke-WebRequest -Uri $asset.browser_download_url -OutFile resterm.exe
# Optionally move to a directory on PATH:
Move-Item resterm.exe "$env:USERPROFILE\bin\resterm.exe"

クイックスタート

mkdir my-api && cd my-api
resterm init
resterm

resterm initは、すぐに使い始められる小さなプロジェクトを作成します。生成されたrequests.httpにはローカルのモックシナリオと、アサーション、ベアラ認証、JSONマッチング、json-rules、@for-eachをカバーするいくつかのリクエストが含まれています。g Shift+mを押してモックサーバーを起動し、Ctrl+Enterでカーソル下のリクエストを送信します。

initなしでRestermを直接開くこともできます。restermを実行し、URLを入力してCtrl+Enterを押すだけです。curlコマンドを貼り付けることもできます — これも動作します。

同じファイルはTUIなしでも実行できます:

resterm run --request CreateUser requests.http

リクエストファイル

Restermは標準的なHTTP構文をサポートしていますが、設定と自動化のための# @ディレクティブによってそれをはるかに超えています:

# @setting base-url https://api.example.com/v1/

### Create users
// Send this request once for each name in the list.
# @for-each ["david", "tom"] as name
# @when env.mode == "development"
# @assert response.statusCode == 201
POST users
Content-Type: application/json

{"name":"{{= name }}"}

最初のリクエストの前に@settingを置くと、ファイル全体に適用されます。###は新しいリクエストを開始し、ディレクティブはその下のリクエストを繰り返し、制限、またはチェックできます。詳細は_examples/とディレクティブリファレンスをご覧ください。

モックサーバー

モックレスポンスはリクエストと同じファイル内で定義されます(ただし、同じファイルである必要はありません)。例として、1つのルートに対する2つのシナリオ:

### Payment accepted
# @mock method=POST path=/payments name=accepted default=true latency=150ms
HTTP/1.1 202 Accepted
Content-Type: application/json

{"id":"pay_123","status":"pending"}

### Payment declined
# @mock method=POST path=/payments name=declined
# @match query={"mode":"decline"} headers={"X-Tenant":"demo"} json={"amount":0}
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{"error":"amount must be positive"}

1つのファイルまたはディレクトリ全体を配信:

resterm mock ./requests.http
resterm mock --recursive --addr 127.0.0.1:9090 ./requests

クエリ、ヘッダー、ボディでのマッチング、ポーリングテスト用のレスポンスシーケンス、呼び出し検証、ホットリロードについてはモックサーバーリファレンスで説明しています。動作する例: _examples/mocks.http。

トラフィックの記録

アプリケーションをRestermプロキシ経由でルーティングすると、トラフィックをキャプチャしてRestermの.httpファイルにリクエスト、モック、またはその両方として保存できます。

resterm record --upstream https://api.example.com --out captured.http --mode both

アプリケーションのAPIベースURLをhttp://127.0.0.1:9000に向け、Ctrl+Cで記録を停止します。TUIでも:record start --upstream <origin>で同じことができ、さらに:record as-requestと:record as-mockでキャプチャを開いているファイルに挿入できます。

詳細は記録リファレンスをご覧ください。

その他

キー

?を押すとRestermの一般的なヘルプが表示され、Shift+kでカーソル下の項目のヘルプが表示されます。完全な表はUIツアーにあります。クイックスタートでは、以下だけ覚えれば十分です:

• Ctrl+Enterでリクエストを送信
• Tab / Shift+Tabでペインを切り替え
• g pでレスポンスにジャンプ

ドキュメント

• docs/resterm.mdはリクエスト構文、ディレクティブ、スクリプティング、トランスポートを扱っています。
• docs/cli.mdはresterm run、インポーター、コレクション、履歴を扱っています。
• docs/restermscript.mdはRestermScriptのリファレンスです。
• 互換性はv1を通じて安定しているものを示しています。

TUI内では、:help <topic>で組み込みマニュアルが開き、:docs <topic>でインストールされたリリースのWeb版が開きます。

ライセンス

Apache License 2.0。