APIコネクタビルダー

APIコネクタビルダー は何をしますか？

ジョブが汎用HTTPクライアントではなく、リポジトリネイティブな統合サーフェスを追加する場合に使用します。

重要なのは、ホストリポジトリのパターンに一致させることです：

• コネクタレイアウト
• 設定スキーマ
• 認証モデル
• エラーハンドリング
• テストスタイル
• 登録/発見の配線

使用するタイミング

• 「このプロジェクトにJiraコネクタを構築する」
• 「既存パターンに従ってSlackプロバイダを追加する」
• 「このAPI用の新しい統合を作成する」
• 「リポジトリのコネクタスタイルに一致するプラグインを構築する」

ガードレール

• リポジトリに既存の統合アーキテクチャがある場合、新しいものを発明しない
• ベンダードキュメントだけで始めない。まず既存のリポジトリ内コネクタから始める
• リポジトリがレジストリの配線、テスト、ドキュメントを期待している場合、トランスポートコードだけで止めない
• リポジトリに新しい現在のパターンがある場合、古いコネクタを盲目的にコピーしない

ワークフロー

1. ハウススタイルを学ぶ

少なくとも2つの既存コネクタ/プロバイダを調査し、以下をマッピングします：

• ファイルレイアウト
• 抽象化の境界
• 設定モデル
• リトライ/ページネーションの慣習
• レジストリフック
• テストフィクスチャと命名

2. ターゲット統合を絞り込む

リポジトリが実際に必要とするサーフェスのみを定義します：

• 認証フロー
• 主要エンティティ
• コアな読み取り/書き込み操作
• ページネーションとレート制限
• Webhookまたはポーリングモデル

3. リポジトリネイティブなレイヤーで構築する

典型的なスライス：

• 設定/スキーマ
• クライアント/トランスポート
• マッピングレイヤー
• コネクタ/プロバイダエントリポイント
• 登録
• テスト

4. ソースパターンに対して検証する

新しいコネクタはコードベース内で自然に見えるべきであり、異なるエコシステムからインポートされたように見えてはいけません。

参考構造

プロバイダ形式

providers/
  existing_provider/
    __init__.py
    provider.py
    config.py

コネクタ形式

integrations/
  existing/
    client.py
    models.py
    connector.py

TypeScriptプラグイン形式

src/integrations/
  existing/
    index.ts
    client.ts
    types.ts
    test.ts

品質チェックリスト

• 既存のリポジトリ内統合パターンに一致している
• 設定のバリデーションが存在する
• 認証とエラーハンドリングが明示的である
• ページネーション/リトライ動作がリポジトリの規範に従っている
• レジストリ/発見の配線が完了している
• テストがホストリポジトリのスタイルを反映している
• リポジトリが期待する場合、ドキュメント/例が更新されている

関連スキル

• backend-patterns
• mcp-server-patterns
• github-ops