API Patterns

2025年向けのAPI設計原理と意思決定ガイド。 固定パターンをコピーするのではなく、思考力を養う。

🎯 選別読み込みルール

リクエストに関連するファイルだけを読む！ コンテンツマップをチェックして、必要な情報を見つけます。

---

📑 コンテンツマップ

ファイル	説明	読むべき時期
api-style.md	REST vs GraphQL vs tRPC 決定ツリー	API種類を選択する時
rest.md	リソース命名、HTTPメソッド、ステータスコード	REST API を設計する時
response.md	エンベロープパターン、エラー形式、ページネーション	レスポンス構造を決める時
graphql.md	スキーマ設計、使用時機、セキュリティ	GraphQL を検討する時
trpc.md	TypeScript モノレポ、型安全性	TS フルスタックプロジェクト
versioning.md	URI/Header/Query バージョニング	API進化計画を立てる時
auth.md	JWT、OAuth、Passkey、API Keys	認証パターンを選択する時
rate-limiting.md	トークンバケット、スライディングウィンドウ	API保護を実装する時
documentation.md	OpenAPI/Swagger ベストプラクティス	ドキュメント化する時
security-testing.md	OWASP API Top 10、認証/認可テスト	セキュリティ監査時

---

🔗 関連スキル

必要な項目	スキル
API 実装	@[skills/backend-development]
データ構造	@[skills/database-design]
セキュリティの詳細	@[skills/security-hardening]

---

✅ 決定チェックリスト

API 設計前に確認すること:

• API利用者について質問した？
• このコンテキスト向けの API スタイルを選択した？ (REST/GraphQL/tRPC)
• 一貫したレスポンス形式を定義した？
• バージョニング戦略を計画した？
• 認証ニーズを検討した？
• レート制限を計画した？
• ドキュメント化アプローチを定義した？

---

❌ アンチパターン

してはいけないこと:

• すべてにデフォルトで REST を使う
• REST エンドポイントで動詞を使う (/getUsers)
• 一貫性のないレスポンス形式を返す
• 内部エラーをクライアントに公開する
• レート制限をスキップする

すべきこと:

• コンテキストに基づいて API スタイルを選択する
• クライアント要件について質問する
• 徹底的にドキュメント化する
• 適切なステータスコードを使う

---

スクリプト

スクリプト	目的	コマンド
scripts/api_validator.py	API エンドポイント検証	python scripts/api_validator.py <project_path>

使用時機

このスキルは、上記の概要に記載されたワークフローまたはアクションを実行する際に適用できます。

制限事項

• このスキルは、タスクが上記で説明されたスコープに明確に合致する場合のみ使用してください。
• 出力を環境固有の検証、テスト、または専門家によるレビューの代替として扱わないでください。
• 必要な入力、権限、安全境界、または成功基準が不足している場合は、立ち止まって明確化を求めてください。