reverse-engineering-api

API のリバースエンジニアリングスキル

このスキルでは、次の方法で Web API をリバースエンジニアリングできます。

1. HAR 記録を有効にしてブラウザーを操作する
2. キャプチャしたネットワークトラフィックを分析する
3. 本番環境で使用できる Python API クライアントを生成する

前提条件

• Playwright MCP：ブラウザー制御用の Playwright MCP ツールにアクセスできる必要があります
• HAR 記録：HAR ファイルを記録するようにブラウザーが設定されている必要があります
• Python：分析スクリプトと生成したクライアントの実行に使用します

ワークフローの概要

[User Task] -> [Browser Capture] -> [HAR Analysis] -> [API Client Generation] -> [Testing & Refinement]

フェーズ 0：準備（HAR ヘルパースクリプトの使用）

利用可能なヘルパースクリプト

このスキルには、HAR 分析用の Python ユーティリティが含まれています。保存場所は次のとおりです。

スクリプトディレクトリ： plugins/reverse-api-engineer/skills/reverse-engineering-api/scripts/

利用可能なスクリプト：

• har_filter.py - HAR ファイルを API エンドポイントのみに絞り込みます
• har_analyze.py - エンドポイント情報を構造化して抽出します
• har_validate.py - 生成されたコードを HAR 分析結果と照合して検証します
• har_utils.py - 共有ユーティリティ関数

スクリプトの使用手順

コードを最適に生成するには、これらのスクリプトを順番に使用します。

# 1. Filter HAR to remove noise (static assets, analytics, CDN)
python {SKILL_DIR}/scripts/har_filter.py {har_path} --output filtered.har --stats

# 2. Analyze endpoints and extract patterns
python {SKILL_DIR}/scripts/har_analyze.py filtered.har --output analysis.json

# 3. Read analysis for code generation guidance
cat analysis.json

# 4. Generate API client code based on analysis

# 5. Validate generated code
python {SKILL_DIR}/scripts/har_validate.py api_client.py analysis.json

スクリプトを使用する理由

har_filter.py の利点：

• HAR ファイルのサイズを 80～90% 削減します（ノイズを除去）
• 実際の API 呼び出しに分析対象を絞ります
• コード生成の品質を大幅に向上させます
• フィルタリングされた内容を示す統計情報を出力します

har_analyze.py の利点：

• 構造化されたエンドポイント情報を提供します
• 認証パターンを自動検出します
• ページネーションの仕組みを特定します
• リクエスト／レスポンスのスキーマを抽出します
• パターンごとにエンドポイントをグループ化します

har_validate.py の利点：

• すべてのエンドポイントが実装されていることを確認します
• 認証処理を検証します
• 適切なエラー処理が行われていることを確認します
• カバレッジスコアを計算します（90 以上である必要があります）
• 不足している機能を特定します

タスクの追跡

TodoWrite を使用してワークフローの進捗を追跡します。

• タスクを pending、in_progress、または completed としてマークします
• in_progress にできるタスクは、一度に 1 つだけです
• すべてのタスクを完了してください。途中で終了しないでください

TodoWrite の使用例：

TodoWrite([
  {"content": "Filter HAR using har_filter.py", "status": "in_progress", "activeForm": "Filtering HAR"},
  {"content": "Analyze HAR using har_analyze.py", "status": "pending", "activeForm": "Analyzing endpoints"},
  {"content": "Generate API client", "status": "pending", "activeForm": "Generating code"},
  {"content": "Validate using har_validate.py", "status": "pending", "activeForm": "Validating code"},
  {"content": "Test implementation", "status": "pending", "activeForm": "Testing API client"}
])

重要： タスクを追跡することで、ワークフローを最後まで実行できます。タスクを省略したり、途中で終了したりしないでください。

フェーズ 1：HAR 記録を有効にしたブラウザーキャプチャ

ブラウザーの起動

API をキャプチャするためにブラウザーセッションを開始するときは、次の手順を実行します。

1. Playwright MCP を使用して HAR 記録を有効にし、ブラウザーを起動します
2. 一意の実行 ID を生成します：{run_id}
3. HAR の出力先を設定します：~/.reverse-api/runs/har/{run_id}/recording.har

キャプチャ中

必要な API 呼び出しを発生させるため、自律的に操作します。

• ログインフロー（認証をキャプチャ）
• データ取得（GET エンドポイントをキャプチャ）
• フォーム送信（POST／PUT エンドポイントをキャプチャ）
• ページネーション（クエリパラメーターのパターンをキャプチャ）

ブラウザーを閉じるとき

ブラウザーが閉じたら、HAR ファイルの場所を確認します。

HAR file saved to: ~/.reverse-api/runs/har/{run_id}/recording.har

フェーズ 2：HAR 分析

HAR ファイルの読み込み

HAR ファイルは、次の構造を持つ JSON です。

{
  "log": {
    "entries": [
      {
        "request": {
          "method": "GET|POST|PUT|DELETE",
          "url": "https://api.example.com/endpoint",
          "headers": [...],
          "postData": {...}
        },
        "response": {
          "status": 200,
          "headers": [...],
          "content": {...}
        }
      }
    ]
  }
}

関連するエントリの絞り込み

次の項目を除外してノイズを取り除きます。

• 静的アセット：.js、.css、.png、.jpg、.svg、.woff、.ico
• 分析ツール：google-analytics、segment、mixpanel、hotjar
• 広告：doubleclick、adsense、facebook.com/tr
• CDN リソース：cloudflare、cdn.、static.

次の項目に注目します。

• API エンドポイント：/api/、/v1/、/v2/、/graphql
• JSON レスポンスを返す XHR／Fetch リクエスト
• 認証ヘッダーを含むリクエスト

パターンの抽出

関連する各エンドポイントについて、次の情報を抽出します。

1. URL パターン：ベース URL、パス、クエリパラメーター
2. メソッド：GET、POST、PUT、DELETE、PATCH
3. ヘッダー：
   • 必須ヘッダー（Authorization、Content-Type、カスタムヘッダー）
   • 任意ヘッダー（User-Agent、Accept）
4. リクエストボディ：JSON スキーマ、フォームデータの構造
5. レスポンススキーマ：JSON 構造、ステータスコード
6. 認証：references/AUTH_PATTERNS.md を参照

フェーズ 3：API クライアントの生成

コード構造

次の内容を含む Python モジュールを生成します。

{output_dir}/
  api_client.py    # Main API client class
  README.md        # Usage documentation

api_client.py テンプレート

"""
Auto-generated API client for {domain}
Generated from HAR capture on {date}
"""

import requests
from typing import Optional, Dict, Any, List
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)


class {ClassName}Client:
    """API client for {domain}."""
    
    def __init__(
        self,
        base_url: str = "{base_url}",
        session: Optional[requests.Session] = None,
    ):
        self.base_url = base_url.rstrip("/")
        self.session = session or requests.Session()
        self._setup_session()
    
    def _setup_session(self):
        """Configure session with default headers."""
        self.session.headers.update({
            "User-Agent": "Mozilla/5.0 (compatible)",
            "Accept": "application/json",
            # Add other required headers
        })
    
    def _request(
        self,
        method: str,
        endpoint: str,
        **kwargs,
    ) -> requests.Response:
        """Make an HTTP request with error handling."""
        url = f"{self.base_url}{endpoint}"
        try:
            response = self.session.request(method, url, **kwargs)
            response.raise_for_status()
            return response
        except requests.exceptions.RequestException as e:
            logger.error(f"Request failed: {e}")
            raise
    
    # Generated endpoint methods go here
    def get_example(self, param: str) -> Dict[str, Any]:
        """
        Fetch example data.
        
        Args:
            param: Description of parameter
            
        Returns:
            JSON response data
        """
        response = self._request("GET", f"/api/example/{param}")
        return response.json()


# Example usage
if __name__ == "__main__":
    client = {ClassName}Client()
    # Example calls

コード品質要件

生成されるすべてのコードには、以下を含める必要があります。

1. すべてのパラメーターと戻り値の型ヒント
2. すべての公開メソッドのドックストリング
3. try-except ブロックによるエラー処理
4. デバッグ用のログ記録
5. 接続を再利用するためのセッション管理
6. 検出されたパターンに基づく認証処理

フェーズ 4：テストと調整

生成したクライアントのテスト

クライアントを生成したら、以下を行います。

1. 使用例のセクションを実行します
2. レスポンスが期待される構造と一致することを確認します
3. 発生したエラーに対処します

反復プロトコル

問題を修正するための試行回数は最大 5 回です。

Attempt 1: Initial implementation
  - What was tried
  - What failed (if anything)
  - What was changed

Attempt 2: Refinement
  ...

よくある問題

問題	解決策
403 Forbidden	不足しているヘッダーを追加し、認証を確認します
ボット検出	ステルスモードを有効にした Playwright に切り替えます
レート制限	待機時間を設け、Retry-After ヘッダーを尊重します
セッションの有効期限切れ	トークンの更新ロジックを実装します
CORS エラー	サーバー側のリクエストを使用します（Python には適用されません）

ドメインの調査（任意）

キャプチャーを行う前に、ドメインの構造を把握するためにマッピングを行うとよいでしょう。

マッパースクリプトの使用

scripts/mapper.py を実行して、以下をすばやく検出します。

• ドメインまたはサブドメイン上のすべてのページ
• サブドメイン

これは、マルチテナントのウェブサイト向けにスクリプトを汎用化する際に役立ちます。

たとえば、Ashby ATS や Workday の場合、スクリプトを汎用化しようとする際に、同じ ATS を使用している他の企業を見つけるのに役立ちます。

python scripts/mapper.py https://example.com

サイトマップパーサーの使用

scripts/sitemap.py を実行して、サイトマップから URL を抽出します。

python scripts/sitemap.py https://example.com

出力先

• HAR ファイル：~/.reverse-api/runs/har/{run_id}/
• 生成されたスクリプト：./{task_name}

セッション例

User: "Create an API client for the Apple Jobs website"


1. [Browser Capture]
   Launch browser with HAR recording
   Navigate to jobs.apple.com
   Perform search, browse listings
   Close browser
   HAR saved to: ~/.reverse-api/runs/har/{run_id}/recording.har

   Note: you can monitor browser requests with the Playwright MCP

2. [HAR Analysis]
   Found endpoints:
   - GET /api/role/search?query=...
   - GET /api/role/{id}
   Authentication: None required (public API)

3. [Generate Client]
   Create : {task_name}/api_client.py
   
4. [Test]
   Ran example usage - Success!
   
5. [Summary]
   Generated Apple Jobs API client with:
   - search_roles(query, location, page)
   - get_role(role_id)
   Files: ./{task_name}/