Agent skill · software engineering · affaan-m
api-design
リソース命名、ステータス コード、ページネーション、フィルタリング、エラー応答、バージョン管理、およびレート制限を含む REST API デザイン パターン。
Why this skill is useful
Provides specific REST API design patterns and conventions that the AI wouldn't reliably generate on its own.
What it needs
About 4k tokens when loaded. Last updated 2026-08-06. 238,342 stars on the source repository.
What this skill does
API デザイン パターン 一貫性のある開発者フレンドリーな REST API を設計するための規約とベスト プラクティス。 アクティブ化するとき 新しい API エンドポイントを設計しているとき 既存の API 契約をレビューしているとき ページネーション、フィルタリング、またはソートを追加しているとき API のエラー処理を実装しているとき API バージョン管理戦略を計画しているとき パブリックまたはパートナー向けの API を構築しているとき リソース デザイン URL 構造 命名規則 HTTP メソッドとステータス コード メソッド セマンティクス メソッド べき等 セーフ 使用対象 -------- -------- -------- --------- GET はい はい リソースを取得 POST いいえ いいえ リソースを作成、アクションをトリガー PUT はい いいえ リソースの完全な置換 PATCH いいえ いいえ リソースの部分的な更新 DELETE はい いいえ リソースを削除 PATCH は適切な実装でべき等にすることができます ステータス コード リファレンス 一般的な間違い 応答フォーマット 成功応答 コレクション応答（ページネーション付き） エラー応答 応答エンベロープ バリエーション ページネーション オフセット ベース（シンプル） 長所: 実装が簡単、「N ページにジャンプ」をサポート 短所: 大きなオフセット（OFFSET 100000）で低速、同時挿入で矛盾 カーソル ベース（スケーラブル） 長所: 位置に関わらず一貫性のあるパフォーマンス、同時挿入では安定 短所: 任意のページへのジャンプができない、カーソルが不透明 どちらを使用するか ユースケース ページネーション タイプ ---------- ---------------- 管理ダッシュボード、小さなデータセット（<10K） オフセット 無限スクロール、フィード、大きなデータセット カーソル パブリック API カーソル（デフォルト）とオフセット（オプション） 検索結果 オフセット（ユーザーはページ番号を期待） フィルタリング、ソート、検索 フィルタリング ソート 全文検索 スパース フィールドセット 認証と認可 トークン ベース認証 認可パターン レート制限 ヘッダー レート制限ティア ティア 制限 ウィンドウ ユースケース ----- ------- -------- ---------- 匿名 30/分 IP あたり パブリック エンドポイント 認証済み 100/分 ユーザーあたり 標準 API アクセス プレミアム 1000/分 API キーあたり 有料 API プラン 内部 10000/分 サービスあたり サービス間通信 バージョン管理 URL パス バージョン管理（推奨） 長所: 明示的、ルーティングが簡単、キャッシャブル 短所: バージョン間で URL が変更される ヘッダー バージョン管理 長所: クリーンな URL 短所: テストが困難、忘れやすい バージョン管理戦略 実装パターン TypeScript (Next.js API ルート) API デザイン チェックリスト 新しいエンドポイントを本番環境に配信する前に： [ ] リソース URL は命名規則に従う（複数形、ケバブケース、動詞なし） [ ] 正しい HTTP メソッドが使用されている（読み取り用 GET、作成用 POST など） [ ] 適切なステータス コードが返される（すべてに 200 ではない） [ ] 入力がスキーマで検証される（Zod、Pydantic、Bean Validation） [ ] エラー応答は標準フォーマットに従う（コードとメッセージ付き） [ ] ページネーションはリスト エンドポイントに実装される（カーソルまたはオフセット） [ ] 認証が必要（または明示的にパブリックとしてマーク） [ ] 認可が確認される（ユーザーは自分のリソースにのみアクセス可能） [ ] レート制限が設定される [ ] 応答は内部詳細をリークしない（スタック トレース、SQL エラー） [ ] 既存のエンドポイントと命名が一貫している（camelCase vs snakecase） [ ] ドキュメント化される（OpenAPI/Swagger スペック更新）
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills affaan-m/api-design--1c7be9