APIにおけるPOST,PUT,PATCHの違い
[質問]
REST APIで、"POST"メソッド、"PUT"メソッド、"PATCH"メソッドを、どのように使い分けるのですか
[回答] Gemini
REST APIにおける「POST」「PUT」「PATCH」の使い分けは、「リソースに対して何を行いたいか」という意図と、「べき等性（Idempotency）」の有無で整理すると非常に分かりやすくなります。
1. 各メソッドの役割と違い
| メソッド | 役割 | データの状態 | べき等性 |
|---|---|---|---|
| POST | 新規作成 | リソースを新しく作る | なし (実行するたびに増える) |
| PUT | 置換（上書き） | 既存データを丸ごと入れ替える | あり (何度やっても同じ状態) |
| PATCH | 部分更新 | 既存データの一部だけ書き換える | なし (実装によるが基本はなし) |
2. 具体的な使い分けの判断基準
POST：新しいリソースの作成
親となるリソースに対して、新しい子要素を追加する場合に使用します。サーバー側でIDを採番することが多いため、同じリクエストを2回送ると、同じ内容のデータが2つ作成されます。
- 例: ブログ記事を新規投稿する、ユーザー登録をする。
- パスの例:
POST /articles
PUT：リソースの完全な置き換え
特定のリソースを、クライアントから送った内容で「丸ごと上書き」する場合に使用します。
- 注意点: 送信しなかったフィールドがある場合、その項目は「空」や「デフォルト値」で更新（削除）されてしまうのが本来の仕様です。
- 例: ユーザー情報の全プロフィール項目を更新する。
- パスの例:
PUT /articles/123
PATCH：リソースの部分的な変更
リソースの「一部の項目だけ」を変更したい場合に使用します。ネットワークの帯域を節約でき、予期せぬ項目の上書きを防げるため、実務では更新処理にPATCHが好まれることが多いです。
- 例: 記事の「タイトル」だけを変更する、ステータスを「公開」から「下書き」に変える。
- パスの例:
PATCH /articles/123
3. 「べき等性（べきとうせい）」とは？
使い分けを考える上で重要な概念です。
「ある操作を1回行っても、複数回行っても、結果が同じであること」
- PUTはべき等:
x = 10という操作は何度繰り返してもxは10です。 - POSTはべき等ではない: 実行するたびに新しいデータ（ID: 1, ID: 2...）が生成されるため、結果が変わります。
まとめ：どれを使うべきか
- 新しく作りたいとき →
POST - 既存のものを「これに差し替えて」と言いたいとき →
PUT - 既存のものの「ここだけ直して」と言いたいとき →
PATCH
現在開発されているマイクロブログのようなアプリケーションでは、記事の投稿には POST、タイトルや本文の修正には PATCH を採用するのが一般的でスマートな設計と言えます。
次に、これらのメソッドを FastAPI などのフレームワークで実装する際の具体的なコード例を確認してみますか？