rest-ops

REST パターン

RESTful API の設計パターンと HTTP のセマンティクスに関するクイックリファレンスです。

HTTP メソッド

メソッド	目的	冪等性	キャッシュ可能
GET	リソースを取得します	はい	はい
POST	新しいリソースを作成します	いいえ	いいえ
PUT	リソース全体を置き換えます	はい	いいえ
PATCH	部分的に更新します	場合によります	いいえ
DELETE	リソースを削除します	はい	いいえ

基本的なステータスコード

コード	名前	用途
200	OK	本文を伴う成功
201	Created	POST の成功（Location ヘッダーを追加します）
204	No Content	本文なしの成功
400	Bad Request	構文が無効です
401	Unauthorized	認証されていません
403	Forbidden	認可されていません
404	Not Found	リソースが存在しません
422	Unprocessable	検証エラー
429	Too Many Requests	レート制限中です
500	Server Error	内部エラー

リソース設計

GET    /users              # List
POST   /users              # Create
GET    /users/{id}         # Get one
PUT    /users/{id}         # Replace
PATCH  /users/{id}         # Update
DELETE /users/{id}         # Delete

# Query parameters
GET /users?page=2&limit=20          # Pagination
GET /users?sort=created_at:desc     # Sorting
GET /users?role=admin               # Filtering

セキュリティチェックリスト

• HTTPS/TLS のみを使用します
• 認証には OAuth 2.0 または JWT を使用します
• すべての入力を検証します
• クライアントごとにレート制限を設定します
• CORS ヘッダーを設定します
• URL に機密データを含めません
• 機密性の高いレスポンスには no-store を使用します

よくある間違い

間違い	修正方法
URL に動詞を含める	/getUsers → /users
深くネストする	フラット化するか、クエリパラメーターを使用します
エラーに 200 を使用する	適切な 4xx/5xx を使用します
ページネーションを使わない	コレクションには必ずページネーションを設定します
レート制限がない	不正利用を防止します

クイックリファレンス

タスク	パターン
ページネーション	?page=2&limit=20
並べ替え	?sort=field:asc
フィルタリング	?status=active
必要なフィールドのみ取得	?fields=id,name
関連データを含める	?include=orders

使用する場面

• 新しい API エンドポイントを設計するとき
• HTTP メソッドとステータスコードを選択するとき
• キャッシュヘッダーを実装するとき
• レート制限を設定するとき
• エラーレスポンスを構成するとき

追加リソース

詳細なパターンについては、以下を読み込んでください。

• ./references/status-codes.md - 例を含むステータスコードの完全なリファレンス
• ./references/caching-patterns.md - Cache-Control、ETag、CDN のパターン
• ./references/rate-limiting.md - レート制限の戦略とヘッダー
• ./references/response-formats.md - エラー、バージョニング、一括操作、HATEOAS