215.txt

[3] [[HTTP]] の [DFN[[CODE(HTTP)@en[[[PATCH]]]] [[メソッド]]]]は、
差分による[[資源]]の部分的な更新を行わせます。

;; 全体の更新を行う [CODE(HTTP)@en[[[PUT]]]] とは異なり、一部分のみを更新します。

* 仕様書

- [6] [[RFC 5789]] [CSECTION@en[PATCH Method for HTTP]] ([[IETF提案標準]])
<http://tools.ietf.org/html/rfc5789>

* メソッドの性質

- [11] [[冪等]]ではありません。 [SRC[>>6]]
- [12] [[安全]]ではありません。 [SRC[>>6]]

* パッチ文書

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

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

;; [22] [CODE(HTTP)@en[[[Request-URI]]]] で表される対象の[[実体頭欄]]も変更したい場合は、
それが可能な[[MIME型]]を利用して[[パッチ文書]]を記述するしかありません。

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

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

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

* パッチの対象

[8] [[パッチ]]を当てる対象となる[[文書]]は [CODE(HTTP)@en[[[Request-URI]]]]
により表されます。[[鯖]]はその対象が存在しなければ新たに作成しても[['''構いません''']]し、
[CODE(HTTP)[[[404]]]] を返すなどしても構いません。また、副作用的に
[CODE(HTTP)@en[[[Request-URI]]]] 以外を変更しても構いません。[SRC[>>6]]

;;
[9] 
具体例として、一般的な [[diff]] コマンドが複数のファイルを変更できることが挙げられています。
[SRC[>>6]]

* 衝突

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

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

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

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

* 原子性

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

* キャッシュとの関係

[17] [[キャッシュ]]を経由して [CODE(HTTP)@en[[[PATCH]]]] [[要求]]がなされた場合、
その [CODE(HTTP)@en[[[Request-URI]]]] によって識別される既に[[キャッシュ]]された[[エントリー]]は[[腐敗]]したものとして扱う[['''べきです''']]。
[SRC[>>6]]

[18] [CODE(HTTP)@en[[[PATCH]]]] [[要求]]に対する[[応答]]は、
明示的に[[新鮮度]]の情報 ([CODE(HTTP)@en[[[Expires]]]],
[CODE(HTTP)@en[[[max-age]]]] など) が含まれており、 [CODE(HTTP)@en[[[Content-Location]]]]
も含まれていて [CODE(HTTP)@en[[[Request-URI]]]] と一致する場合に限り、
[[キャッシュ可能]]です。
[SRC[>>6]]

;; [19] [CODE(HTTP)@en[[[Content-Location]]]] が一致することにより、それがその [[URL]]
で表される[[資源]]の[[表現]]であることがわかります。

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

* 誤り応答

[31] 成功の場合も誤りの場合も、使用する[[状態符号]]には特に制限はなく、
[[鯖]]は最も適切な[[状態符号]]を選ぶことができます。

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

* 歴史

** RFC 2068 における定義

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

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

*** 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.

[CODE(HTTP)[PATCH]] 方式は [CODE(HTTP)[[[PUT]]]] 方式と似ていますが、
実体は [CODE(ABNF)[[[Request-URI]]]] で識別される資源の元の版と資源の
[CODE(HTTP)[PATCH]] 動作を適用した後に望まれる内容の差異の一覧を含みます。
差異の一覧は実体の媒体型 (たとえば [CODE(MIME)[[[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.

要求が[[キャッシュ]]を通じて渡され、 [CODE(ABNF)[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.

継ぎ当てした資源をどう配置するのか、以前のものがどうなるのかを決定する実際の方法は、
完全に起源サーバーが定義します。資源の元の版を
[CODE(HTTP)[[[Content-Version]]]] 頭欄を含めて継ぎ当てする場合は、要求実体は
元の [CODE(HTTP)[Content-Version]] 頭欄の値に対応する
[CODE(HTTP)[[[Derived-From]]]] 頭欄を含めなければ'''なりません'''。
[[応用]]は版付け関係を構築し、版衝突を解決するためにこれらの欄を使うことを推奨します。

> PATCH requests must obey the message transmission requirements set
out in section 8.2.

[CODE(HTTP)[PATCH]] 要求は、8.2節のメッセージ転送要件に従わなければなりません。

> Caches that implement PATCH should invalidate cached responses as
defined in section 13.10 for PUT.

[CODE(HTTP)[PATCH]] を実装する[[キャッシュ]]は、
13.10節で [CODE(HTTP)[[[PUT]]]] について定義されているようにキャッシュ応答を無効化するべきです。

**** License

[[RFCのライセンス]]

** RFC 2616 における削除

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

* 例

** パッチをあてる例

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

[PRE(HTTP example code)[
PATCH /file.txt HTTP/1.1
Host: www.example.com
Content-Type: application/example
If-Match: "e0023aa4e"
Content-Length: 100

[・・・差分・・・]
]PRE]
... という要求に対して、
[PRE(HTTP example code)[
HTTP/1.1 204 No Content
Content-Location: /file.txt
ETag: "e0023aa4f"

]PRE]

- [[要求]]は差分の適用元の [CODE(HTTP)@en[[[ETag]]]] を [CODE(HTTP)@en[[[If-Match]]]] に入れて[[条件付要求]]とし、意図しない適用を防いでいます。
- [[応答]]は成功したことだけを [CODE(HTTP)@en[[[204]]]] で伝えています。変更後の [CODE(HTTP)@en[[[ETag]]]] も知らせています。

* 関連

** [CODE(HTTP)@en[PUT]] との関係

[10] [CODE(HTTP)@en[[[PUT]]]] は全体を更新し、 [CODE(HTTP)@en[[[PATCH]]]]
は一部を更新する点が大きく異なります。 [SRC[>>6]]

[23] [CODE(HTTP)@en[[[PATCH]]]] の方がかえって [CODE(HTTP)@en[[[PUT]]]]
よりサイズが大きくなってしまうような場合もあるので、[[クライアント]]はどちらが適当か考える必要があります。
[SRC[>>6]]

** [CODE(HTTP)@en[[[POST]]]] との関係

[24] [CODE(HTTP)@en[[[POST]]]] はより一般的で、「なんでもあり」なので、
[CODE(HTTP)@en[[[PATCH]]]] 相当の操作を [CODE(HTTP)@en[[[POST]]]] で行うこともできますし、
実際よく行われています。

[25] 変更したい対象が [CODE(HTTP)@en[[[Request-URI]]]] から明確に予測可能でない場合は、
[CODE(HTTP)@en[[[PATCH]]]] よりも [CODE(HTTP)@en[[[POST]]]] を使うのが適切です。 [SRC[>>6]]

* メモ

[1]
[CITE@en-US[snellspace.com &#187; Blog Archive &#187; Beyond APP - Partial updates]] ([CODE[2007-06-10 13:10:13 +09:00]] 版) <http://www.snellspace.com/wp/?p=683>
([[名無しさん]] [WEAK[2007-06-10 04:13:12 +00:00]])

[2]
[CITE@en-US[snellspace.com &#187; Blog Archive &#187; PATCH Update]] ([CODE[2007-07-27 23:41:24 +09:00]] 版) <http://www.snellspace.com/wp/?p=710>
([[名無しさん]] [WEAK[2007-07-27 14:44:20 +00:00]])