API Connector Design スキル

概要

外部APIとの統合において、適切な設計パターンと実装指針を提供します。RESTful API、GraphQL、WebSocketなど様々なAPI形式に対応し、認証、エラーハンドリング、パフォーマンス最適化を網羅します。

API統合タイプ分類

1. RESTful API

特徴:

• HTTPメソッドによるCRUD操作
• ステートレス通信
• リソース指向設計

設計パターン:

GET    /resources          - リソース一覧取得
GET    /resources/{id}     - 個別リソース取得
POST   /resources          - リソース作成
PUT    /resources/{id}     - リソース更新（全体）
PATCH  /resources/{id}     - リソース更新（部分）
DELETE /resources/{id}     - リソース削除

ベストプラクティス:

• Content-Type: application/json の一貫した使用
• 適切なHTTPステータスコードの返却
• HALまたはJSON:APIフォーマットの採用検討

2. GraphQL

特徴:

• スキーマベースの型システム
• 単一エンドポイント
• 柔軟なクエリ構造

設計パターン:

query {
  user(id: "123") {
    name
    email
    posts {
      title
    }
  }
}

mutation {
  createUser(input: { name: "John" }) {
    id
    name
  }
}

ベストプラクティス:

• N+1問題の回避（DataLoader使用）
• 複雑度制限の実装
• 適切なエラーハンドリング

3. WebSocket

特徴:

• 双方向リアルタイム通信
• 持続的接続
• 低レイテンシ

設計パターン:

Client <──────────────> Server
    │ CONNECT              │
    │ ─────────────────────▶
    │ MESSAGE              │
    │ ◀────────────────────│
    │ MESSAGE              │
    │ ─────────────────────▶
    │ DISCONNECT           │
    │ ─────────────────────▶

ベストプラクティス:

• ハートビートによる接続維持
• 再接続ロジックの実装
• メッセージキューイング

4. Webhook

特徴:

• イベント駆動型
• プッシュ型通知
• 非同期処理

設計パターン:

┌─────────┐   Event発生   ┌──────────┐   POST   ┌─────────┐
│ Service │ ────────────▶ │ Webhook  │ ────────▶│ Your    │
│         │               │ Endpoint │          │ Server  │
└─────────┘               └──────────┘          └─────────┘

認証・認可パターン

API Key認証

// ヘッダーベース
headers: {
  'X-API-Key': process.env.API_KEY
}

// クエリパラメータベース（非推奨）
url: `${baseUrl}?api_key=${apiKey}`

セキュリティ考慮事項:

• 環境変数での管理
• HTTPS通信の強制
• ローテーション計画

OAuth 2.0

Authorization Code Flow:

1. Client → Authorization Server: 認可リクエスト
2. User: ログイン・承認
3. Authorization Server → Client: 認可コード
4. Client → Authorization Server: トークンリクエスト
5. Authorization Server → Client: アクセストークン

実装チェックリスト:

• state パラメータによるCSRF対策
• PKCE（Proof Key for Code Exchange）実装
• リフレッシュトークンの安全な保存
• トークン有効期限管理

JWT（JSON Web Token）

// トークン構造
header.payload.signature

// 検証ステップ
1. 署名検証
2. 有効期限（exp）チェック
3. 発行者（iss）検証
4. 対象者（aud）検証

Rate Limiting対策

検出方法

// レスポンスヘッダーから制限情報を取得
const rateLimitInfo = {
  limit: response.headers["X-RateLimit-Limit"],
  remaining: response.headers["X-RateLimit-Remaining"],
  reset: response.headers["X-RateLimit-Reset"],
};

リトライ戦略

指数バックオフ:

const delay = Math.min(
  initialDelay * Math.pow(backoffFactor, attempt),
  maxDelay,
);
// ジッターを追加（同時リトライ回避）
const jitteredDelay = delay * (0.5 + Math.random());

リトライ条件:

設計時の判断基準

API統合チェックリスト

• 適切なAPI統合タイプが選択されているか？
• 認証方式はセキュリティ要件を満たすか？
• Rate Limitingとリトライ戦略は定義されているか？
• タイムアウト設定は適切か？
• エラーハンドリングは網羅的か？

パフォーマンスチェックリスト

• 接続プーリングが実装されているか？
• キャッシュ戦略が定義されているか？
• ペイロードサイズは最適化されているか？
• 圧縮（gzip）が有効か？

リソース参照

詳細なパターンと実装例については以下を参照:

• 認証フロー詳細: cat .claude/skills/api-connector-design/resources/authentication-flows.md
• Rate Limiting戦略: cat .claude/skills/api-connector-design/resources/rate-limiting-strategies.md
• エラーハンドリング: cat .claude/skills/api-connector-design/resources/error-handling-patterns.md

テンプレート参照

• APIクライアントテンプレート: cat .claude/skills/api-connector-design/templates/api-client-template.ts
• 認証設定テンプレート: cat .claude/skills/api-connector-design/templates/auth-config-template.json

スクリプト実行

# API接続テスト
node .claude/skills/api-connector-design/scripts/test-api-connection.mjs <base-url>

# 認証フロー検証
node .claude/skills/api-connector-design/scripts/validate-auth-flow.mjs <config.json>

関連スキル