[3] PATCH は、 差分を指定して資源の一部を更新される要求メソッドです。

全体の更新を行う PUT とは異なり、一部分のみを更新します。

仕様書

意味

[12] PATCH メソッドは、 要求の payload body に記述した変更の集合を対象資源に適用することを求めるものです >>6。

[11] 冪等メソッドでも安全メソッドでもありません >>6。

[43] この「パッチ」(「差分」) は、通常の意味よりも拡大解釈されています。 一般的には diff 命令などでバイト列や文字列としての違いを計算した結果がパッチであると理解されていますが、 HTTP 要求メソッドとしての PATCH は既存の資源に対する何らかの変更の指示を表すために使われているようです。 その「何らかの変更の指示」は一般的なパッチ形式であることよりは、 その資源専用の指示の記述方法を採用していることが多いようです。

パッチ文書

[7] 変更の内容を記述した文書をパッチ文書patch documentといいます >>6。パッチ文書のMIME型は特に限定されておらず、任意のものを使えます。 実装が強制されているMIME型もありません。

[21] PATCH 要求のHTTPヘッダーはすべてパッチ文書に適用されるものであって、 パッチによる変更を表しているものではありません。従って、(記録目的等を除いて) 鯖には蓄積されるべきではありません。 >>6

[22] ヘッダーも変更したい場合は、それが可能なMIME型を利用してパッチ文書を記述するしかありません。[38] これも PUT 要求との違いです。

[27] 鯖は、パッチ文書の書式が正しくないときは 400 を返すべきです。 「書式が正しくない」はパッチ文書のMIME型の定義によります。 >>6

[28] 鯖は、パッチ文書のMIME型に未対応の時は 415 を返すべきです。 その応答には Accept-Patch 頭欄も含めるべきです。 >>6

[29] 鯖は、パッチ文書を理解できて、しかし処理できない場合、 422 を返すべきです。 例えば、XML文書が適用対象で、 パッチの適用によって整形式でなくなる場合には 422 を返すことができます。 >>6

[40] 鯖は、 application/json や application/xml のような一般的で PATCH における意味を定義していない MIME型をパッチ文書として使えると考えるべきではありません >>39。

[41] PATCH で使うことを想定したと明記されている差分の記述形式には、 次のものがあります。

処理

[8] 鯖は、対象資源が存在しなければ、新たに作成しても構いませんし、 404 を返すなどしても構いません。また、 副作用的に対象資源以外を変更しても構いません。>>6

[9] 一般的な diff コマンドは複数のファイルを変更できます >>6。

[16] 鯖は操作を原子的アトミックatomicに行わなければなりません。 複数の資源に変更が及ぶ場合であっても、すべて変更されるかすべて変更されないかのいずれかでなければなりません。 操作の途中に要求があっても、部分的に変更されたものを応答として返してはなりません。 >>6

[32] 誤りを表す応答の payload body は、誤りを説明する十分な情報を含んだものであるべきです。 そのMIME型は特に規定されていません。 >>6

キャッシュ

[17] 要求URLが同じキャッシュ項目があれば、腐敗したものとするべきです >>6。

[18] 応答は、新鮮度 (Expires: や Cache-Control: max-age) が明示されており、 かつ Content-Location: が対象URL と一致する (応答の payload body が資源の表現である) 場合には、キャッシュ可能です >>6。

[19] POST メソッドも PATCH と同じ意味でキャッシュ可能です。 GET や HEAD がキャッシュ可能であるというのとは若干意味が異なります。

[20] PATCH への応答は GET や HEAD に対してのみ使うことができます。その他のメソッドには使ってはなりません。 >>6

[37] PATCH メソッドに対する応答にも使えません。

衝突

[13] パッチを当てる操作は一般には冪等ではありませんし、順序に依存します。 複数のパッチを同時に当てようとすると、意図しない編集結果になることもあります。

[14] ある基準点に対して差分を記述する形の場合は、 変更元の ETag を If-Match 頭欄に指定するなどして条件付要求として PATCH メソッドを発行すれば、意図しない更新は避けることができます。 そのような操作を行うクライアントは条件付要求を使うべきです。 >>6

[15] ログなどでどんどん追記していくような形で差分が記述される場合はそのような衝突は起こらないので、 配慮は不要です。 >>6

[30] 鯖は衝突により変更を適用できないときは 409 を返すことができます。 >>6

歴史

RFC 2068 における定義

[4] PATCH メソッドは公式には RFC 2068 ではじめて定義されました。ただし完全な規定ではなく、参考として挙げられているに過ぎませんでした。

[31] RFC 5789 の定義は雰囲気こそこの RFC 2068 の定義と似ていますが、 基本的に互換性はありません。

[36] RFC 2068 (HTTP/1.1) 19.6.1.1 PATCH

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 について定義されているようにキャッシュ応答を無効化するべきです。

RFC 2616 における削除

[5] RFC 2068 の改訂版である RFC 2616 では、 RFC 2068 中のあまり実装されていない機能は省かれており >>34、 PATCH メソッドも説明されていませんでした。

[35] 使われていないとは述べられていますが、廃止とはされていませんでした。
  • [34] RFC 2616 - Hypertext Transfer Protocol -- HTTP/1.1 ( 版) http://tools.ietf.org/html/rfc2616#page-175

例

パッチをあてる例

[26] 単純な差分適用の例 >>6

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 にしておくのが無難でしょう。

[42] GitHub API v3 ( 版) https://developer.github.com/v3/

PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests.

[44] Rest | Flowdock API () https://www.flowdock.com/api/rest

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