PUT

使い方

PUT リクエストは、同梱された表現を指定された URI に保存するようサーバーに指示します。リソースがすでに存在する場合、サーバーはその状態全体を新しい表現で置き換えます。その URI にリソースが存在しない場合、サーバーは新たに作成します。

冪等性

PUT は冪等です。同じ PUT リクエストを複数回送信しても、1回送信した場合と同じサーバー状態になります。これは、送信を繰り返すと重複したリソースが作成されたり処理が複数回発生したりする POST とは対照的です。

冪等性により、PUT はネットワーク障害後に安全に再試行できます。先のリクエストが届いたかどうか確信が持てないクライアントは、意図しない副作用のリスクなしにリクエストを再送できます。

コンテントネゴシエーション

サーバーは、受け取った表現を自身の制約に照らして検証します。Content-Type が期待どおりで内容が整形式であれば、サーバーはリソースを保存し、新規リソースには 201 Created を、置換には 200 OK または 204 No Content を返します。

メディアタイプに互換性がない場合、サーバーは 415 Unsupported Media Type を返します。409 Conflict レスポンスは、バージョンの不一致など、コンテンツタイプとは無関係な状態の競合を示します。

PUT と POST の比較

POST は処理をターゲットリソースに委ねます。PUT は表現が属する正確な URI を指定します。/articles/42 への PUT は、その記事を /articles/42 に保存します。/articles への POST は、サーバーが選んだ URI に新しい記事を作成するようコレクションに依頼します。

PUT と PATCH の比較

PUT はリソース全体を置き換えます。PATCH は部分的な変更を適用します。PUT で単一のフィールドを更新するには、完全な表現を送信する必要があります。PATCH は変更分のみを送信します。

リソースの作成

クライアントがプレーンテキストファイルを /docs/setup.txt に保存します。サーバーはリソースを作成し、201 Created で応答します。

リクエスト

PUT /docs/setup.txt HTTP/1.1
Host: api.example.re
Content-Type: text/plain
Content-Length: 24

Install, configure, run.

レスポンス

HTTP/1.1 201 Created
Location: /docs/setup.txt
Content-Length: 0

リソースの置換

クライアントが /users/42 にある既存の JSON リソースを置き換えます。サーバーは 200 OK で更新を確認し、保存された表現を返します。

リクエスト

PUT /users/42 HTTP/1.1
Host: api.example.re
Content-Type: application/json
Content-Length: 43

{"name":"Alice","email":"alice@example.re"}

レスポンス

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 51

{"id":42,"name":"Alice","email":"alice@example.re"}

条件付き更新

If-Match を使った条件付きリクエストは、他のクライアントによって変更されたリソースの上書きを防ぎます。ETag の値により、更新が想定されたバージョンにのみ適用されることが保証されます。

リクエスト

PUT /config/app.json HTTP/1.1
Host: api.example.re
Content-Type: application/json
If-Match: "a1b2c3"
Content-Length: 27

{"debug":false,"port":8080}

レスポンス

HTTP/1.1 204 No Content
ETag: "d4e5f6"

CORS

クロスオリジンの PUT リクエストは常に CORS プリフライトを発生させます。ブラウザはまず OPTIONS リクエストを送信し、サーバーがターゲットリソースに対する PUT を許可しているかを確認します。

レスポンスステータスコード

201 Created は、サーバーがターゲット URI に新しいリソースを作成したことを示します。これは、その場所に以前リソースが存在しなかった場合に適用されます。

200 OK は既存のリソースが置換されたことを確認し、レスポンスのボディに更新後の表現を含みます。

204 No Content は、レスポンスボディなしで置換を確認します。これは、クライアントが保存された表現の返却を必要としない場合によく使われます。

412 Precondition Failed は、If-Match の条件が満たされなかったことを示します。クライアントが提示した ETag の値が現在のリソースバージョンと一致しないため、サーバーは他のクライアントによる変更の上書きを防ぐために更新を拒否します。

409 Conflict は、前提条件とは無関係なアプリケーションレベルの状態の競合を示します。たとえば、コンテンツのマージ競合や、クライアントが手動で解決する必要のあるバージョン管理上の衝突などです。