Rest APIで使われるHTTPメソッド
| メソッド名 | 役割 | 冪等性 | 安全性 |
|---|---|---|---|
| GET | リソースの取得 | ○ | ○ |
| POST | リソースの作成 | × | × |
| PUT | リソースの全体更新（置き換え） | ○ | × |
| PATCH | リソースの部分更新（一部を更新） | × | × |
| DELETE | リソースの削除 | ○ | × |
冪（べき）等性とは同じ操作を1回行っても何回行っても同じ結果が得られる性質のことです。
同じ結果というのは、リソースの状態のことで、HTTPレスポンスのことではありません。
例えば、DELETEメソッドは冪等ですが、通常1回目のリクエストでは200レスポンスを、2回目以降のリクエストを404レスポンスを返します。
このようにレスポンスは異なるものの、リソースの状態は同じです。（特定のデータが消えた状態は同じ）
上記の役割や冪等性はあるべき論です。
意味としては正しくないですが、GETでリソースを変更しようと思えば可能です。
PATCHは冪等ではありません。ただし冪等であるように振る舞うことは可能です。
HTTP PUT メソッドは、ドキュメントの完全な置換のみを許可します。PUT とは違って、PATCH はべき等ではありません。すなわち、同一の PATCH リクエストが連続しておこなわれると、異なる効果が得られる可能性があります。ただし PATCH リクエストがべき等になるようにリクエストすることは可能です。
PATCH - HTTP | MDN
安全性はリソースの変化が生じるかどうかを示す性質です。
上記ではGET以外はリソースの変更が生じるので安全ではありません。
以下に各メソッドの役割を記載しますが、どのHTTPメソッドを使うべきかは、解釈が分かれます。
先述のとおり、あるべき論なので。
下記URLにあるようにメソッドの種類によって、同じURLでも違う処理を割り当てることが可能です。
GET
GETメソッドはリソースの取得に用いられます。
ブラウザではページの表示によく使用されます。
考えられる処理:
- データ取得
- ファイルダウンロード
URL例:
- /api/users
- /api/users/:user_id
- /api/users/:user_id/photos
POST
リソースを作成するメソッドです。
リソース名がサーバーで割り振られてデータができます。
ブラウザではフォームデータ送信によく使用されます。
考えられる処理:
- データ新規作成
PUT
リソースの全体更新（まるごと置き換え）を行うメソッドです。
考えられる処理:
- ファイルアップロード（ファイルがなければ新規アップロードされて、あれば上書きされる）
URL例:
- /api/users/:user_id/photos/:photo_id
- /api/articles/:article_id/bookmark
PATCH
リソースの部分更新を行うメソッドです。
Railsでは更新をかけるたびに、updated_at（レコード更新時刻）は変更になるので冪等ではないPATCHメソッドを採用しているとされています。
Now let’s think about ordinary edit forms in typical Ruby on Rails applications. How many times are we sending a complete representation for replacement? Not always, perhaps we could say that it is even rare in practice that you do so. For example, the conventional created_at and updated_at timestamps normally can’t be set by end-users, though they are often considered to belong to the representation of resources that map to records.
この理屈でいくと他のウェブアプリケーションフレームワークの更新処理もPATCHになるでしょう。
考えられる処理:
- データ更新
URL例:
- /api/users/:user_id
DELETE
リソースを削除するメソッドです。
考えられる処理:
- データ削除
URL例:
- /api/users/:user_id
- /api/articles/:article_id/bookmark