mcpField
A
api-patterns

api-patterns

github.com/sickn33開発48.7k1.4k 回インストール今日更新
リポジトリ

api-patterns について

api-patternsは、利用者やデプロイ上の制約に応じたAPI設計を支援するスキルです。API形式、レスポンス、バージョニング、認証、レート制限、文書化、安全性の検討を扱います。

主な機能

  1. 01API形式の選定
  2. 02REST、GraphQL、tRPCの指針
  3. 03レスポンスとページネーション設計
  4. 04バージョニングと認証の選択
  5. 05レート制限と文書化の指針
  6. 06ローカルでのヒューリスティックなコード走査

活用シーン

  1. 01新しいエンドポイント契約の定義
  2. 02既知の利用者に適したAPI形式の選択
  3. 03ページネーションや互換性変更の計画
  4. 04許可されたテスト範囲でのAPI安全性確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/sickn33/agentic-awesome-skills --skill api-patterns

インストール後、Claude Code で/api-patternsを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

rest.md
auth.md
api-style.md
response.md
documentation.md
graphql.md
rate-limiting.md
security-testing.md
trpc.md
versioning.md
scripts/
api_validator.py

詳細

API パターン

コンシューマーとデプロイ制約に紐づく API 設計上の判断。 固定されたパターンをコピーするのではなく、THINK することを学びましょう。

🎯 選択的読書ルール

リクエストに関連するファイルのみを読んでください！ コンテンツマップを確認し、必要なものを見つけましょう。

📑 コンテンツマップ

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

🔗 関連スキル

必要なものスキル
API 実装@[skills/backend-architect]
データ構造@[skills/database-design]
セキュリティの詳細@[skills/api-security-best-practices]

✅ 意思決定チェックリスト

API を設計する前に：

  • API コンシューマーについてユーザーに確認しましたか？
  • このコンテキストに合った API スタイルを選びましたか？ (REST/GraphQL/tRPC)
  • 一貫したレスポンス形式を定義しましたか？
  • バージョニング戦略を計画しましたか？
  • 認証のニーズを検討しましたか？
  • レート制限を計画しましたか？
  • ドキュメントの方針を定義しましたか？

❌ アンチパターン

やってはいけないこと：

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

やるべきこと：

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

スクリプト

スクリプト目的コマンド
scripts/api_validator.pyローカルのヒューリスティックなソーススキャン（スキーマ検証ではありません）python3 skills/api-patterns/scripts/api_validator.py <project_path>

使用する場面

新しいエンドポイントの契約を定義するとき、既知のコンシューマーに対して REST/GraphQL/tRPC を選択するとき、あるいはページネーション、エラー、認証、互換性の動作を変更するときに使用します。既存の契約内のバグについては、タスクが変更を許可していない限り、その契約を維持してください。

入力と手順

コンシューマーとデプロイ済みバージョン、想定されるペイロードサイズ、アクセスルール、互換性の義務、および 1 つの具体的な操作を記録します。マップ内の関連ファイルを読み、現実的な選択肢を比較したうえで、リクエスト/レスポンスの例と拒否ケースを指定します。ビルド時に共有される型は、独立してデプロイされたクライアントが互換性を保ち続けることを保証しません。

実例

入力：クライアントがページをめくっている間に、公開注文リストが変更されます。有界のページサイズと、安定した (created_at, id) 順序に対するカーソルを選択します。次のカーソルの形式、認可フィルター、削除されたレコードまたは無効なカーソルの動作を定義します。同じタイムスタンプが 2 つあるケースと、ページ間での挿入をテストします。期待される結果：約束されたスナップショットセマンティクス内で ID の重複がないこと。新しく挿入された行が表示される可能性があるかどうかを文書化します。

制限事項

  • Python ヘルパーは、正規表現と浅い JSON/YAML チェックを使用して、最大 15 個の一致するファイルをスキャンします。その出力はトリアージのヒントであり、OpenAPI 検証、認可監査、デプロイ承認ではありません。
  • GraphQL のクエリ形状、tRPC の推論、HTTP メソッド名は、リソースの認可や後方互換性を強制しません。
  • レート制限だけでは、すべてのリソース枯渇を防ぐことはできません。サイズ、同時実行数、時間、プロバイダーコストの境界は操作によって異なります。
  • セキュリティチェックは、分離されたアカウントと定義されたスコープを用いて、認可されたローカル/テストターゲットに対してのみ実行してください。

コメント

Markdown 対応