browser-to-api

Browser to API

リプレイ駆動型の API 検出です。browser-trace のキャプチャを取り込み、CDP のリクエスト／レスポンスイベントを対応付け、観測された URL をテンプレート化し、サンプルから JSON スキーマを推定して、OpenAPI 3.1 ドキュメントと、人が読みやすいカバレッジレポートを出力します。

このスキルはトラフィックをキャプチャしません。browser-trace の cdp/network/*.jsonl バケットを対象とした、完全にオフラインの後処理のみを行います。2 つのスキルを組み合わせて使います。

browser-trace    →  .o11y/<run>/cdp/network/{requests,responses}.jsonl
browser-to-api   →  .o11y/<run>/api-spec/index.html + openapi.yaml + client.mjs

使用する場面

• ユーザーが、サードパーティまたは仕様が公開されていない Web サイト API の OpenAPI ドキュメントを必要としている場合。
• ユーザーが browser-trace の実行結果を持っており、そこからエンドポイントとスキーマを抽出したい場合。
• 仕様が公開されていないサイト向けのクライアント／SDK を開発している場合。
• どのフローが仕様の対象範囲を広げるかを示すカバレッジレポートが必要な場合。

ユーザーがトラフィックのキャプチャを希望している場合は、まず browser-trace を案内してください。

2 ステップのワークフロー

1. browser-trace でキャプチャする（必要に応じて browse network on で本文も取得）

# Local example against an existing debuggable Chrome target
TARGET=9222

node ../browser-trace/scripts/start-capture.mjs "$TARGET" my-site
browse open about:blank --cdp "$TARGET"
browse network on                                    # capture request/response bodies
browse open https://example.com
# ...drive whatever flows you want covered...

# Snapshot the bodies dir BEFORE turning capture off (the temp dir is shared
# per-session, so subsequent `browse network on` runs would mix your bodies
# with whatever a future capture writes if you skip this step).
cp -r "$(browse network path | jq -r .path)" .o11y/my-site/cdp/network/bodies/
browse network off

node ../browser-trace/scripts/stop-capture.mjs my-site
node ../browser-trace/scripts/bisect-cdp.mjs my-site

browse network on は任意ですが、強く推奨します。これを使わない場合、仕様にはレスポンス本文のスキーマが含まれません（browse cdp が使用する CDP の大量のイベントデータには本文が埋め込まれていないためです）。有効にすると、リクエスト本文（すでに CDP でキャプチャ済み）とレスポンス本文の両方が、CDP の requestId によってトレースに結合されます。

2. 仕様を生成する

node scripts/discover.mjs --run .o11y/my-site
# → .o11y/my-site/api-spec/index.html          ← open this
#   .o11y/my-site/api-spec/client.mjs
#   .o11y/my-site/api-spec/openapi.yaml
#   .o11y/my-site/api-spec/openapi.json
#   .o11y/my-site/api-spec/report.md
#   .o11y/my-site/api-spec/confidence.json
#   .o11y/my-site/api-spec/samples/*.json
#   .o11y/my-site/api-spec/intermediate/*.jsonl

discover.mjs は <run>/cdp/network/bodies/ を自動検出します。別の場所にある本文キャプチャを使う場合（例：スナップショットを取得していない場合や、実行中の browse network ディレクトリを使いたい場合）は、--bodies <path> を明示的に指定してください。

3. HTML レポートを開く

discover.mjs の実行が完了したら、必ず生成された HTML レポートを開いてください。

open .o11y/my-site/api-spec/index.html

レポートは、サーバーを必要としない単体で動作する HTML ファイルです。検出された各オペレーションを、変数、クライアントでの使用方法、リクエスト／レスポンスの例、および下部に生成された client.mjs のスニペットを含む展開可能なカードとして表示します。これが主な成果物です。必ずユーザーのために開いてください。

CLI フラグ

フラグ	必須	意味
--run <path>	はい	browser-trace の実行ディレクトリへのパス
--out <path>	いいえ	出力ディレクトリ。デフォルトは <run>/api-spec/
--bodies <path>	いいえ	トレースに結合する browse network のキャプチャディレクトリ（存在する場合、<run>/cdp/network/bodies/ から自動検出）
--include <regex>	いいえ	正規表現に一致する URL のみを含めます（複数回指定可能）
--exclude <regex>	いいえ	URL を除外します（複数回指定可能。デフォルトの除外対象に追加）
--origins <list>	いいえ	カンマ区切りのオリジン許可リスト（例：api.example.com,example.com）
--format <yaml|json|both>	いいえ	出力形式。デフォルトは both
--title <string>	いいえ	OpenAPI の info.title。デフォルトは主要なオリジンから生成
--redact <list>	いいえ	マスキング対象に追加するヘッダー名／JSON キー（カンマ区切り）
--min-samples <n>	いいえ	含めるエンドポイントごとの最小サンプル数。デフォルトは 1
--stage <name>	いいえ	実行するステージを 1 つだけ指定します：load、filter、normalize、infer、emit

出力レイアウト

<run>/api-spec/
├── index.html                visual report — open this (self-contained, no server)
├── client.mjs                zero-dep fetch client with typed functions per operation
├── openapi.yaml              machine-readable spec
├── openapi.json              mirror
├── report.md                 markdown summary + curl examples
├── confidence.json           per-endpoint confidence + normalization flags
├── samples/                  redacted request/response examples
│   └── <method>__<path-hash>.json
└── intermediate/             pipeline byproducts (paired/filtered/endpoints jsonl)

browse cdp と browse network から取得できるもの

相互に補完する2つのキャプチャソースです。

ソース	提供される情報	制限事項
browse cdp（browser-trace で使用）	リクエストのメソッド／URL／ヘッダー／postData、レスポンスのステータス／ヘッダー／mimeType、完全なイベントタイミング	レスポンス本文は埋め込まれません。 本文は Network.getResponseBody で取得する必要がありますが、firehose は取得しません。
browse network on（別コマンド）	ディスク上に保存されるリクエスト本文とレスポンス本文。CDP の requestId をキーにします	キャプチャディレクトリは browse セッションごとに共有されます。別の browse network on によって上書きされる前にスナップショットを取得してください。

discover.mjs は、--bodies <path> を渡すと browse network ディレクトリから本文を取得します（または <run>/cdp/network/bodies/ に保存すると自動検出されます）。照合は requestId に基づいて行われます。browse network は各 request.json に id として書き込み、直接結合します。

本文がある場合の変更点：

• ✅ パスのテンプレート化、クエリパラメーターのスキーマ、ステータスコード、コンテンツタイプは、どちらの場合も同じです。
• ✅ リクエスト本文のスキーマ — CDP の postData で十分です。本文ディレクトリは、postData 以外のケースで役立ちます。
• ✅ レスポンス本文のスキーマ — 実際のサンプルから完全に推論されます。本文がない場合は、{ description, content: <mimeType> } の骨組みが生成されます。

レポートでは、レスポンス本文のサンプルがないエンドポイントすべてにフラグが付けられます。

自動ノイズフィルタリング

正規化ステージでは、インフラ由来のノイズが自動的に分類され、除外されます。

• トラッキング／分析 — /track、/pixel、/beacon、/impression、/pageview、/dag/v* を含むパス
• ボット対策 — Akamai（/akam/）、フィンガープリントのペイロード（sensor_data）、難読化された複数セグメントのパス
• セッション関連の処理 — /session、/authenticate/start、Cookie 同意、A/B テストのエンドポイント
• HTML ページのレンダリング — text/html を返す GET リクエスト（API ではなく、レンダリングされたページ）

通常、キャプチャしたトラフィックの60〜80%が除外されます。誤検出は --include フラグで含めることができます。

GraphQL／多重化エンドポイントの分解

単一のエンドポイント（/dapi/fe/gql など）が異なる operationName の値で呼び出されると、スキルが自動的にそれらを個別の論理オペレーションに分割します。それぞれに以下が用意されます。

• OpenAPI のパスエントリー（例：/dapi/fe/gql [Autocomplete]）
• そのオペレーションのサンプルのみから推論されたリクエスト／レスポンスのスキーマ
• レポート内の Curl の例と変数テーブル

検出は、本文のフィールド（operationName、method、action）とクエリパラメーター（opname、op）に基づいて行われます。GraphQL（APQ およびインライン）、JSON-RPC、および類似のディスパッチパターンに対応しています。

制限事項

• カバレッジはキャプチャしたフローの範囲内に限られます。 トレースで実行されていないエンドポイントは表示されません。スキルは完全性を証明できません。
• スキーマは帰納的に推論されるものであり、契約ではありません。 すべてのサンプルに含まれていても、サーバー上ではフィールドが任意の場合があります。
• 認証は観測されますが、仕様として定義されるわけではありません。 スキルは認証に見えるヘッダーを x-observed-auth 拡張に記録しますが、セキュリティスキームとしては扱いません。
• パスのテンプレート化はヒューリスティックです。 数値／UUID／16進数／スラッグのパターンがセグメントごとに検出されます。曖昧な URL には confidence.json でフラグが付けられます。
• 秘匿化は可能な限り行われます。 デフォルトの秘匿化では一般的な認証情報を対象としますが、アプリ固有のシークレットが残る可能性があります。既知のカスタムヘッダー／キーには --redact を使用してください。

ベストプラクティス

1. ドキュメント化したいフローを実際に操作します。 ブラウザーのトレースが豊富なほど、仕様も充実します。
2. ノイズの多いサイトでは --origins を使います。 マーケティングページは多数の分析用ホストにアクセスするため、対象とする API のオリジンに絞り込みます。
3. まず report.md を確認します。 発見された各操作の curl ですぐに実行できる例とレスポンスのサンプルが記載されています。
4. 最終ドキュメントに確度の高いエンドポイントだけを載せたい場合は、--min-samples を 2 以上に引き上げます。 裾野にあるエンドポイントは除外できます。
5. レスポンスボディのスキーマが重要な場合は、browse network on と組み合わせます。 CDP の大量のイベントだけではリクエストボディは取得できますが、レスポンスボディは取得できません。

パイプラインの内部構造とファイル形式のリファレンスについては、REFERENCE.md を参照してください。