[3] PATCH は、
差分を指定して資源の一部を更新される要求メソッドです。
[12] PATCH メソッドは、
要求の payload body に記述した変更の集合を対象資源に適用することを求めるものです
>>6。
[11] 冪等メソッドでも安全メソッドでもありません >>6。
[43] この「パッチ」(「差分」) は、通常の意味よりも拡大解釈されています。
一般的には diff 命令などでバイト列や文字列としての違いを計算した結果がパッチであると理解されていますが、
HTTP 要求メソッドとしての PATCH
は既存の資源に対する何らかの変更の指示を表すために使われているようです。
その「何らかの変更の指示」は一般的なパッチ形式であることよりは、
その資源専用の指示の記述方法を採用していることが多いようです。
[7] 変更の内容を記述した文書をパッチ文書といいます >>6。パッチ文書のMIME型は特に限定されておらず、任意のものを使えます。 実装が強制されているMIME型もありません。
[21] PATCH 要求のHTTPヘッダーはすべてパッチ文書に適用されるものであって、
パッチによる変更を表しているものではありません。従って、(記録目的等を除いて)
鯖には蓄積されるべきではありません。 >>6
[27] 鯖は、パッチ文書の書式が正しくないときは 400 を返すべきです。
「書式が正しくない」はパッチ文書のMIME型の定義によります。 >>6
[28] 鯖は、パッチ文書のMIME型に未対応の時は 415 を返すべきです。
その応答には Accept-Patch 頭欄も含めるべきです。
>>6
[29] 鯖は、パッチ文書を理解できて、しかし処理できない場合、
422 を返すべきです。 例えば、XML文書が適用対象で、
パッチの適用によって整形式でなくなる場合には 422 を返すことができます。
>>6
[40] 鯖は、 application/json や application/xml
のような一般的で PATCH における意味を定義していない
MIME型をパッチ文書として使えると考えるべきではありません >>39。
[8] 鯖は、対象資源が存在しなければ、新たに作成しても構いませんし、
404 を返すなどしても構いません。また、
副作用的に対象資源以外を変更しても構いません。>>6
[16] 鯖は操作を原子的に行わなければなりません。 複数の資源に変更が及ぶ場合であっても、すべて変更されるかすべて変更されないかのいずれかでなければなりません。 操作の途中に要求があっても、部分的に変更されたものを応答として返してはなりません。 >>6
[32] 誤りを表す応答の payload body は、誤りを説明する十分な情報を含んだものであるべきです。 そのMIME型は特に規定されていません。 >>6
[17] 要求URLが同じキャッシュ項目があれば、腐敗したものとするべきです >>6。
[18] 応答は、新鮮度 (Expires: や
Cache-Control: max-age) が明示されており、
かつ Content-Location: が対象URL
と一致する (応答の payload body が資源の表現である)
場合には、キャッシュ可能です >>6。
[20] PATCH への応答は
GET や HEAD
に対してのみ使うことができます。その他のメソッドには使ってはなりません。
>>6
[13] パッチを当てる操作は一般には冪等ではありませんし、順序に依存します。 複数のパッチを同時に当てようとすると、意図しない編集結果になることもあります。
[14] ある基準点に対して差分を記述する形の場合は、
変更元の ETag を If-Match 頭欄に指定するなどして条件付要求として
PATCH メソッドを発行すれば、意図しない更新は避けることができます。
そのような操作を行うクライアントは条件付要求を使うべきです。 >>6
[15] ログなどでどんどん追記していくような形で差分が記述される場合はそのような衝突は起こらないので、 配慮は不要です。 >>6
[4] PATCH メソッドは公式には RFC 2068
ではじめて定義されました。ただし完全な規定ではなく、参考として挙げられているに過ぎませんでした。
[31] RFC 5789 の定義は雰囲気こそこの RFC 2068 の定義と似ていますが、 基本的に互換性はありません。
The PATCH method is similar to PUT except that the entity contains a list of differences between the original version of the resource identified by the Request-URI and the desired content of the resource after the PATCH action has been applied. The list of differences is in a format defined by the media type of the entity (e.g., "application/diff") and MUST include sufficient information to allow the server to recreate the changes necessary to convert the original version of the resource to the desired version.
PATCH 方式は PUT 方式と似ていますが、
実体は Request-URI で識別される資源の元の版と資源の
PATCH 動作を適用した後に望まれる内容の差異の一覧を含みます。
差異の一覧は実体の媒体型 (たとえば application/diff)
で定義された書式であり、サーバーが資源の元の版から望む版に変換するのに必要な変更を再生成するのに十分な情報を含まなければなりません。
If the request passes through a cache and the Request-URI identifies a currently cached entity, that entity MUST be removed from the cache. Responses to this method are not cachable.
要求がキャッシュを通じて渡され、 Request-URI
が現在キャッシュされている実体を識別するなら、
その実体はキャッシュから削除しなければなりません。
この方式への応答はキャッシュ可能ではありません。
The actual method for determining how the patched resource is placed, and what happens to its predecessor, is defined entirely by the origin server. If the original version of the resource being patched included a Content-Version header field, the request entity MUST include a Derived-From header field corresponding to the value of the original Content-Version header field. Applications are encouraged to use these fields for constructing versioning relationships and resolving version conflicts.
継ぎ当てした資源をどう配置するのか、以前のものがどうなるのかを決定する実際の方法は、
完全に起源サーバーが定義します。資源の元の版を
Content-Version 頭欄を含めて継ぎ当てする場合は、要求実体は
元の Content-Version 頭欄の値に対応する
Derived-From 頭欄を含めなければなりません。
応用は版付け関係を構築し、版衝突を解決するためにこれらの欄を使うことを推奨します。
PATCH requests must obey the message transmission requirements set out in section 8.2.
PATCH 要求は、8.2節のメッセージ転送要件に従わなければなりません。
Caches that implement PATCH should invalidate cached responses as defined in section 13.10 for PUT.
PATCH を実装するキャッシュは、
13.10節で PUT について定義されているようにキャッシュ応答を無効化するべきです。
[5] RFC 2068 の改訂版である RFC 2616 では、 RFC 2068 中のあまり実装されていない機能は省かれており >>34、
PATCH メソッドも説明されていませんでした。
PATCH /file.txt HTTP/1.1 Host: www.example.com Content-Type: application/example If-Match: "e0023aa4e" Content-Length: 100 [・・・差分・・・]
... という要求に対して、
HTTP/1.1 204 No Content Content-Location: /file.txt ETag: "e0023aa4f"
PUT との関係[10] PUT 要求は、 payload body が鯖に蓄積されているものの修正版そのものであり、
蓄積されているものをまるごと置き換えることを求めています。
一方 PATCH 要求は、 payload body
が修正版を得るためにどう変更するべきかの指示となっています。 >>6
[23] PATCH の方がかえって PUT
よりサイズが大きくなってしまうような場合もあるので、クライアントはどちらが適当か考える必要があります。
>>6
POST との関係[24] POST はより一般的で、「なんでもあり」なので、
PATCH 相当の操作を POST で行うこともできますし、
実際よく行われています。
[25] 変更したい対象が Request-URI から明確に予測可能でない場合は、
PATCH よりも POST を使うのが適切です。 >>6
[1]
snellspace.com » Blog Archive » Beyond APP - Partial updates (2007-06-10 13:10:13 +09:00 版) <http://www.snellspace.com/wp/?p=683>
(名無しさん 2007-06-10 04:13:12 +00:00)
[2]
snellspace.com » Blog Archive » PATCH Update (2007-07-27 23:41:24 +09:00 版) <http://www.snellspace.com/wp/?p=710>
(名無しさん 2007-07-27 14:44:20 +00:00)
[423] tus resumable upload protocol ( ( 版)) <http://tus.io/protocols/resumable-upload.html#5-3-2>
[424] Performance Tips - Gmail API — Google Developers ( ( 版)) <https://developers.google.com/gmail/api/guides/performance>
[33] Web API などで PATCH メソッドを
POST メソッドの代わりに使うことが最近増えていますが、
どちらを選ぶかは宗教的な判断なので、特にこだわりがなければ広く利用されている
POST にしておくのが無難でしょう。
PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests.
PATCH is used for most update methods instead of PUT because of PUT’s inefficiency and inconvenient requirements of idempotency.
[45] RFC 8132 - PATCH and FETCH Methods for the Constrained Application Protocol (CoAP) () <https://tools.ietf.org/html/rfc8132>
[46] RFC 8144 - Use of the Prefer Header Field in Web Distributed Authoring and Versioning (WebDAV) () <https://tools.ietf.org/html/rfc8144#section-3.1>
PUTとは異なり、一部分のみを更新します。