HTTP の PATCH メソッド

これはインターネット標準トラックの文書です。

本書はインターネットエンジニアリングタスクフォース (IETF) の成果物です。IETF コミュニティの合意を表しています。公開審査を経てインターネットエンジニアリング運営グループ (IESG) による公開承認を受けています。インターネット標準に関する詳細は RFC 5741 のセクション 2 を参照してください。

本書の現状、訂正情報 (errata)、およびフィードバックの送付方法に関する情報は http://www.rfc-editor.org/info/rfc5789 で入手できます。

Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

本仕様は、新しい HTTP/1.1 のメソッド PATCH（リソースに対して部分的な修正を適用するために使用される）を定義します。参照: [RFC2616]。

相互運用性を向上させエラーを防ぐために新しいメソッドが必要です。PUT メソッドは既にリソースを完全な新しいボディで上書きするよう定義されており、部分的変更に再利用することはできません。そうでなければ、プロキシやキャッシュ、さらにはクライアントやサーバが操作の結果について混乱する可能性があります。POST はすでに使用されていますが、パッチ形式のサポートを発見する標準的な方法がないなど、広範な相互運用性を持ちません。PATCH は以前の HTTP 仕様で言及されていましたが、完全には定義されていませんでした。

本書ではキーワード "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", および "OPTIONAL" は [RFC2119] に記載されたとおりに解釈されます。

さらに、本書は [RFC2616] のセクション 2.1 で定義された ABNF 構文を使用します。

PATCH メソッドは、要求エンティティ内に記述された変更の集合を Request-URI で識別されるリソースに適用するよう要求します。変更の集合はメディアタイプで識別される「パッチ文書」と呼ばれる形式で表現されます。もし Request-URI が既存のリソースを指していない場合、サーバはパッチ文書の種類（null リソースを論理的に修正できるかどうか）や権限等に応じて、新しいリソースを作成してもよい（MAY）です。

PUT と PATCH の違いは、リクエストに含まれるエンティティをどのように処理して Request-URI で識別されるリソースを修正するかに反映されます。PUT リクエストでは、同梱されたエンティティはオリジンサーバに格納されているリソースの修正版と見なされ、クライアントは格納されたバージョンの置換を要求します。一方 PATCH では、同梱されたエンティティはリソースを新しいバージョンにするための指示の集合を含みます。PATCH メソッドは Request-URI で識別されるリソースに影響を与え、また他のリソースに副作用を及ぼすこと（新しいリソースが作成されたり既存のものが修正されたりすること）もあります。

PATCH は [RFC2616] セクション 9.1 に定義されるとおり、安全でも冪等でもありません。

PATCH リクエストは冪等となるように発行することができ、これにより同一リソースに対する短時間での二つの PATCH リクエスト間の競合による悪影響を防ぐ助けになります。複数の PATCH リクエストからの衝突は、ある種のパッチ形式が既知のベースポイントから動作する必要がある場合に PUT の衝突より危険であり、そうでなければリソースを破損する恐れがあります。この種のパッチ適用を行うクライアントは、リソースがクライアントが最後にアクセスした以降に更新されていればリクエストが失敗するような条件付きリクエストを使用するべきです（SHOULD）。例えば、クライアントは PATCH リクエストの If-Match ヘッダに強い ETag を使用できます。

行末にテキストを追加するログファイルや、衝突しない行をデータベース表に追加するような、既知のベースポイントから動作する必要がないパッチ形式もあります。その場合はクライアントリクエストにおける同様の注意は不要です。

サーバは変更集合全体を原子的に適用し、この操作中に部分的に修正された表現を（例えば GET への応答として）提供してはなりません。パッチ文書全体を正常に適用できない場合、サーバはどの変更も適用してはなりません（MUST NOT）。PATCH の成功と見なす条件は、パッチ文書や修正されるリソースの種類により異なり得ます。例えば一般的な diff ユーティリティはディレクトリ階層内の複数ファイルに適用できるパッチ文書を生成できます。原子性の要件は直接影響を受けるすべてのファイルに対して適用されます。ステータスコードや可能なエラー条件の詳細については "Error Handling"（セクション 2.2）を参照してください。

要求がキャッシュを通過し、Request-URI が現在キャッシュされているエンティティを一つ以上識別する場合、それらのエントリは古くなったものとして扱うべきです（SHOULD）。このメソッドへの応答は、明示的な鮮度情報（Expires ヘッダや "Cache-Control: max-age" ディレクティブなど）と、PATCH 応答本文がリソース表現であることを示す Request-URI に一致する Content-Location ヘッダを含む場合にのみキャッシュ可能です。キャッシュされた PATCH 応答は、その後の GET および HEAD リクエストに応答するためにのみ使用でき、他のメソッド（特に PATCH）に応答するために使用してはなりません。

リクエストに含まれるエンティティ-ヘッダは、同梱されたパッチ文書にのみ適用され、修正されるリソース自体には適用してはなりません。したがって、Content-Language ヘッダがリクエストに存在しても、それはパッチ文書に言語があることを意味するにすぎません。サーバはそのようなヘッダをトレース情報として除いて保存すべきではなく、PUT リクエストで使われるのと同じ方法でそれらのヘッダ値を使用すべきではありません。したがって、本書はヘッダを通じてドキュメントの Content-Type や Content-Language を変更する方法を指定していませんが、パッチ文書を通じてこの目的を達成する仕組みを設計することは可能です。

リソースが PATCH で修正可能である保証はありません。さらに、異なるパッチ文書形式が異なる種類のリソースに適切であり、単一の形式がすべてのリソース型に適切であることは期待されません。したがって、実装がサポートする必要のある単一のデフォルトのパッチ文書形式は存在しません。サーバは受信したパッチ文書が Request-URI で識別されるリソースの種類に適切であることを保証しなければなりません（MUST）。

クライアントはいつ PATCH を PUT より使用するかを選択する必要があります。例えば、パッチ文書のサイズが PUT で使用される新しいリソースデータのサイズより大きい場合は、PATCH の代わりに PUT を使用する方が合理的かもしれません。POST と比較するのはさらに難しく、POST は多様な使われ方をし、サーバが選択すれば PUT や PATCH に類する操作を包含し得ます。操作が Request-URI によって識別されるリソースを予測可能な方法で変更しない場合、PATCH や PUT の代わりに POST を検討すべきです。

サーバは、HTTP/1.1 で定義された "Allow" OPTIONS レスポンスヘッダの許可されたメソッド一覧に PATCH を追加することで、PATCH のサポートを告知できます。Accept-Patch ヘッダが存在しなくても、PATCH メソッドは "Allow" ヘッダに表示され得ます。その場合、許可されるパッチ文書の一覧は告知されません。

PATCH のセキュリティ考慮事項は PUT のそれとほぼ同一です（参照: [RFC2616] セクション 9.6）。これにはリクエストの認可（アクセス制御や認証による）や、転送エラーや偶発的な上書きによるデータの破損が含まれます。PUT に使用されるメカニズムは PATCH にも利用できます。以下は PATCH に特に適用される考慮点です。

パッチされたドキュメントは、全体を上書きするドキュメントよりも破損しやすい可能性がありますが、これらの懸念は If-Match リクエストヘッダを使った ETag による条件付きリクエストなどのメカニズムで対処できます（セクション 2 を参照）。PATCH リクエストが失敗した場合、クライアントは GET リクエストを発行してリソースの状態を確認できます。基盤となるトランスポートチャネルが失敗した場合やタイムアウトが発生し PATCH 応答を受信できなかった場合は、クライアントは GET を発行して要求が適用されたかを確認する必要が生じるかもしれません。クライアントは GET 要求がキャッシュをバイパスするように、HTTP 仕様で記述された機構（例えば [RFC2616] のセクション 13.1.6）を使用することを検討してもよいでしょう。

HTTP 中間体が PUT/POST リクエストや GET 応答の本文をチェックしてウイルスを検出しようとすることがあります。PATCH メソッドは、元のドキュメントやパッチ文書のどちらもウイルスではない場合でも、結果がウイルスとなり得るため、そのような監視を複雑にします。このセキュリティ上の考慮は、バイトレンジダウンロードやパッチ文書のダウンロード、圧縮ファイルのアップロードなどにより既に導入されている問題と本質的に異なりません。

個々のパッチ文書には、パッチされるリソースの種類に依存して異なる固有のセキュリティ考慮事項が存在します。例えば、バイナリ資源をパッチする場合の考慮は XML 文書をパッチする場合と異なります。サーバは悪意のあるクライアントが PATCH を使って過大なサーバリソース（CPU、ディスク I/O など）を消費できないよう十分な予防措置を講じる必要があります（MUST）。

PATCH は新しい概念ではなく、最初は Roy Fielding と Henrik Frystyk によって書かれた HTTP 1.1 の草案に登場し、また RFC 2068 のセクション 19.6.1.1 にも現れています。

Adam Roach、Chris Sharp、Julian Reschke、Geoff Clemm、Scott Lawrence、Jeffrey Mogul、Roy Fielding、Greg Stein、Jim Luther、Alex Rousskov、Jamie Lokier、Joe Hildebrand、Mark Nottingham、Michael Balloni、Cyrus Daboo、Brian Carpenter、John Klensin、Eliot Lear、SM、Bernie Hoeneisen に対して、本書のレビューと助言に感謝します。特に Julian Reschke は繰り返しレビューを行い、多くの有用な提案をし、本書の公開に重要な貢献をしました。