[524] PUT
は、要求URLの資源を指定したデータで置き換え (または新規作成)
することを要求するものです。
[525] PUT
は最初期から HTTP 仕様に含まれていた要求メソッドですが、
何度も標準化や実装によって普及が試みられたにも関わらず、広く採用されるに至っていません。
最近では HTML5 によってフォームの提出の方法に追加採用されましたが、
利用・実装されなかったため、削除されました。
[508] PUT
メソッドは、要求メッセージの payload
に含まれる表現によって決まる状態により対象資源の状態を作成または置換することを要求するものです
>>507。
[509] PUT
が成功すれば、同じ対象資源を GET
したら要求に含まれていたのと等価な表現が 200
応答に含まれることが想定されていますが、実際にはそのような GET
より前に他者により変更されたり、起源鯖側で動的な処理が行われたりする可能性を排除できませんから、
必ずしもそれが観察できるわけではありません。 PUT
が成功しても、起源鯖がそれを処理した時点で利用者エージェントの意図が達成されたことだけを表しています。 >>507
[19] WebDAV クライアントは、新しい資源の Content-Type:
が分かっていれば、これを指定するべきです >>14。
[2] 起源鯖は、要求メッセージの payload body や、 payload に含まれるとみなされるヘッダーを保存することが期待されています。
[512] 起源鯖は、 PUT
要求の認識できないヘッダーを
(資源の一部として保存するのではなく) 無視するべきです >>507。
[6] 要求メッセージの Content-Location:
ヘッダーは、そのまま保存するべきではありません (Content-Location:
(>>325))。
[4] それ以外にどのヘッダーが保存されるべきかは明記されていません。
[5] RFC 7231 は、ヘッダーの仕様書に対し、 PUT
で指定されたヘッダーを保存するべきか明記することを検討するよう求めています >>3。
ただし RFC 723x のヘッダーについてはそのような記述はありません。
[20] WebDAV に従うコレクション以外の資源に PUT
が送信された場合で、要求に Content-Type:
が含まれない場合、 Content-Type:
なしの資源を作っても構いませんし、
Content-Type:
を割り当てようと試みても構いません >>14。
[513] 起源鯖は、 PUT
の表現が当該対象資源に関する変更できない鯖の制約を
(あれば) 満たしているか検証するべきです。満たしていない時には、
満たすように変形を加えるか、適切な説明とともにエラーを返すべきです。
状態符号としては、 409
を使うことができます。
Content-Type:
に関する制約の時は、
415
を使うことができます。 >>507
[514] 起源鯖が実際にどのように状態を保存するかは、実装に依存します。 HTTP としてはその方法を規定しません >>507。
[519] PUT
の処理は副作用を持っても構いません >>507。
[15] WebDAV に従う資源でコレクション以外の場合には、
PUT
は GET
で返される表現を置き換えます。
この時特性は再計算されるものもありますが、それ以外は影響を受けません >>14。
[22] WebDAV コレクションに対する PUT
の動作は定義されていません >>14。 405
応答を返しても構いません >>14。
[26] LNR の場合、 PUT
により通常の資源に変換されます >>25。
[510] 起源鯖は、対象資源が現在表現を持っておらず、 PUT
によってその作成に成功した場合には、 201
を送信しなければなりません >>507。
[24] WebDAV に従う資源は、この場合 3xx
を返してはなりません >>23。
[511] 起源鯖は、対象資源が現在表現を持っており、 PUT
によりその編集に成功した場合には、 200
か 204
を送信しなければなりません >>507。
[17] WebDAV に従う鯖は、コレクション以外の資源への
PUT
で適切な親となるコレクション無しで資源を作ってしまうことになる場合には、
409
応答を返さなければなりません >>14。
[10] 成功した場合の応答の payload には、成功した旨の報告を含めることもできますし、
作成・変更した後の資源の表現を含めることもできます。
クライアントは、どちらを希望するかを Prefer: return
により指定できます (が鯖がそれに従う義務はありません)。
[517] 起源鯖は、対象資源の状態を変更せず、他の資源に適用したい場合は、
適切な 3xx
応答を送信しなければなりません。
その場合利用者エージェントはリダイレクトに従うか選ぶことができます。 >>507
[521] 起源鯖は、対象資源に PUT
を認めている場合で、
要求に Content-Range:
ヘッダーが含まれる場合、
payload が一部分しか含まれないのに誤って PUT
を使っている可能性があるため、 400
応答を送信しなければなりません
>>507。
Content-Range:
が適用されることをほのめかす記述があり >>27、
対象資源の一部分を更新できる実装もあった >>28 ようですが、
広く受け入れられた解釈ではなく、 RFC 723x で禁止されたようです。[515] 起源鯖は、要求の表現が変形なしに保存され、 validator header
の値が新しい表現にそのまま適用される場合を除き、
PUT
への応答で validator header を送信してはなりません
>>507。
The PUT method requests that the enclosed entity be stored under the supplied Request-URI. If the Request-URI refers to an already existing resource, the enclosed entity
shouldSHOULD be considered as a modified version of the one residing on the origin server. If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI. If a new resource is created, the origin server MUST inform the user agent via the 201 (Created) response. If an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request. If the resource could not be created or modified with the Request-URI, an appropriate error response SHOULD be given that reflects the nature of the problem. The recipient of the entity MUST NOT ignore any Content-* (e.g. Content-Range) headers that it does not understand or implement and MUST return a 501 (Not Implemented) response in such cases.
PUT
方式は、囲まれた実体を供給した
Request-URI
の元で蓄積することを要求します。
Request-URI
が既に存在する資源を指している時は、
囲まれた実体は起源サーバーにあるものの修正版と考えられるべきです。
Request-URI
が既存の資源を指しておらず、
その URI に要求している利用者エージェントによって新しい資源を定義する能力があるなら、
起源サーバーはその URI に資源を作ることが出来ます。 新しい資源が作られたら、起源サーバーは 301
(作成せし) 応答で利用者エージェントに知らせなければなりません。既存の資源が修正されたなら、 200
(了解) または 204
(無内容) の応答符号を送って要求の成功裏完了を示すべきです。その Request-URI
で資源を作るか修正するかできなかったときは、問題の性質を反映して適切な誤り応答を与えるべきです。実体の受信者は、その理解・実装しない Content-*
頭 (例えば Content-Range
) を無視してはなりませんで、そのような場合には 501
(未実装) 応答を返さなければなりません。
If the request passes through a cache and the Request-URI identifies one or more currently cached entities, those entries
shouldSHOULD be treated as stale. Responses to this method are not cacheable.
要求がキャッシュを通して渡され、 Request-URI
が一つか複数個の現在キャッシュされている実体を識別する時は、
それらの項目は腐敗しているものとして扱うべきです。
この方式への応答はキャッシュ可能ではありません。
The fundamental difference between the POST and PUT requests is reflected in the different meaning of the Request-URI. The URI in a POST request identifies the resource that will handle the enclosed entity
{1945} as data to be processed. That resource{1945,2068} may{2616} might be a data-accepting process, a gateway to some other protocol, or a separate entity that accepts annotations. In contrast, the URI in a PUT request identifies the entity enclosed with the request -- the user agent knows what URI is intended and the server{1945} should notMUST NOT attempt to apply the request to some other resource. If the server desires that the request be applied to a different URI, it MUST send a 301 (Moved Permanently) response; the user agent MAY then make its own decision regarding whether or not to redirect the request.
POST
要求と PUT
要求の本質的な違いは、
Request-URI
の違った意味を反映しています。
POST
要求の URI は囲まれた実体を処理されるデータとして取扱う資源を識別します。
その資源はデータ受入れ過程かもしれませんし、他のプロトコルとの関門かもしれませんし、
注釈を受け入れる別の実体かもしれません。
かわって、 PUT
要求の URI は要求に囲まれた実体のを識別します。
利用者エージェントはどの URI が意図されているかを知っており、
サーバーはその要求を他の資源に適用しようと試みてはなりません。サーバーが要求を異なる URI に適用することを望む時は、 301
(永続的移動) 応答を送らなければなりません。利用者エージェントは要求を再指向するかどうかについて自身の決定を下して構いません。
A single resource MAY be identified by many different URIs. For example, an article
maymight have a URI for identifying "the current version" which is separate from the URI identifying each particular version. In this case, a PUT request on a general URImaymight result in several other URIs being defined by the origin server.
一つの資源は多くの違った URI で識別して構いません。
例えば、ある記事は特定の版を識別する URI とは別に「現行版」
を識別する URI を持つかもしれません。
この場合、一般 URI への PUT
要求は、結果その起源サーバーが定義する幾つかの他の URI
となるかもしれません。
HTTP/1.1 does not define how a PUT method affects the state of an origin server.
HTTP/1.1 は起源サーバーの状態に PUT
方式がどう影響するかを定義しません。
PUT requests
mustMUST obey the message transmission requirements set out in section 8.2.
PUT
要求は8.2節のメッセージ転送要件に従わなければなりません。
Unless otherwise specified for a particular entity-header, the entity-headers in the PUT request SHOULD be applied to the resource created or modified by the PUT.
特定の実体頭で特に指定されていない限り、
PUT
要求の実体頭は PUT
で作成または修正された資源に適用するべきです。
[516] PUT
と POST
は似ていますが、
POST
は対象資源の意味に基づき処理されるのに対し、
PUT
は対象資源の状態を置き換えるものである点が根本的に異なります
>>507。
[518] クライアントではなく鯖側が更新する適切な URL を選ぶ場合には、
PUT
ではなく POST
を使うべきです >>507。
[1] Editing the Web - Detecting the Lost Update Problem Using Unreserved Checkout <http://www.w3.org/1999/04/Editing/>
[504] RFC 7252 - The Constrained Application Protocol (CoAP) ( ( 版)) <http://tools.ietf.org/html/rfc7252#section-5.8.3>
[505] tus resumable upload protocol ( ( 版)) <http://www.tus.io/protocols/resumable-upload.html>
[9] 理論上は PUT
で任意の資源を共通のプロトコルで編集できて便利なのでしょうけど、実際上は
URL の構造や PUT
できる書式、アクセス権限など諸々の事前情報を鯖とクライアントの間で何らかの方法で共有し実装しなければいけないので、
POST
に対する優位性は特に無いのですよね...
Example setting "y" to 5 in the matching document without affecting other fields (using jQuery):
$.ajax( { url: "https://api.mongolab.com/api/1/databases/my-db/collections/my-coll/4e7315a65e4ce91f885b7dde?apiKey=myAPIKey",
data: JSON.stringify( { "$set" : { "y" : 5 } } ),
type: "PUT",
contentType: "application/json" } );
[31] RFC 8144 - Use of the Prefer Header Field in Web Distributed Authoring and Versioning (WebDAV) () <https://tools.ietf.org/html/rfc8144#section-3.1>
[32] RFC 3253 - Versioning Extensions to WebDAV (Web Distributed Authoring and Versioning) () <https://tools.ietf.org/html/rfc3253#section-3.10>
[33] RFC 4791 - Calendaring Extensions to WebDAV (CalDAV) () <https://tools.ietf.org/html/rfc4791#section-5.3.2.1>
[34] 10671 – consider adding support for PUT and DELETE as form methods () <https://www.w3.org/Bugs/Public/show_bug.cgi?id=10671>
Content-Type:
を含む要求のヘッダーの情報を使うとは限りませんから、 常にContent-Type:
が反映されると想定することはできません >>14。