2. PATCH メソッド (The PATCH Method)
2. PATCH メソッド (The PATCH Method)
PATCH メソッドは、Request-URI によって識別されるリソースに、リクエストエンティティ (request entity) に記述された一連の変更を適用することを要求します. この変更のセットは、メディアタイプ (media type) によって識別される "パッチドキュメント (patch document)" と呼ばれる形式で表されます. Request-URI が既存のリソースを指していない場合、サーバーは新しいリソースを作成する場合があります (MAY). これは、パッチドキュメントのタイプ (null リソースを論理的に変更できるかどうか) と権限などに依存します.
PUT リクエストと PATCH リクエストの違いは、Request-URI によって識別されるリソースを変更するために、含まれているエンティティをサーバーが処理する方法に反映されます. PUT リクエストでは、含まれているエンティティは、オリジンサーバー (origin server) に格納されているリソースの変更されたバージョンと見なされ、クライアントは格納されたバージョンを置き換えるよう要求します. しかし、PATCH の場合、含まれているエンティティには、現在オリジンサーバーに存在するリソースを変更して新しいバージョンを生成する方法を記述する一連の命令 (instructions) が含まれています. PATCH メソッドは Request-URI によって識別されるリソースに影響を与え、他のリソースに副作用 (side effects) を持つ場合もあります (MAY). つまり、PATCH を適用することで新しいリソースが作成されたり、既存のリソースが変更されたりする可能性があります.
[RFC2616] のセクション 9.1 で定義されているように、PATCH は安全 (safe) でも冪等 (idempotent) でもありません.
PATCH リクエストは冪等的な方法で発行することができます. これは、同じリソースに対する 2 つの PATCH リクエストが類似した時間枠で衝突 (collisions) することによる悪い結果を防ぐのにも役立ちます. 複数の PATCH リクエストからの衝突は、PUT の衝突よりも危険な場合があります. なぜなら、一部のパッチフォーマットは既知のベースポイント (base-point) から操作する必要があり、そうでなければリソースを破壊する可能性があるためです. この種のパッチアプリケーションを使用するクライアントは、条件付きリクエスト (conditional request) を使用すべきです (SHOULD). これにより、クライアントが最後にアクセスした後にリソースが更新された場合、リクエストが失敗します. たとえば、クライアントは PATCH リクエストの If-Match ヘッダーで強力な ETag [RFC2616] を使用できます.
既知のベースポイントから操作する必要がないパッチフォーマットもあります (たとえば、ログファイルにテキスト行を追加する、またはデータベーステーブルに競合しない行を追加する). この場合、クライアントリクエストで同じ注意は必要ありません.
サーバーは変更セット全体を原子的 (atomically) に適用しなければならず (MUST)、部分的に変更された表現 (representation) を提供してはなりません (たとえば、この操作中に GET に応答する). パッチドキュメント全体を正常に適用できない場合、サーバーはいかなる変更も適用してはなりません (MUST NOT). 成功した PATCH の判定は、パッチドキュメントと変更されるリソースのタイプによって異なる場合があります. たとえば、一般的な 'diff' ユーティリティは、ディレクトリ階層内の複数のファイルに適用されるパッチドキュメントを生成できます. 原子性要件は、そのうちの 1 つだけでなく、パッチの影響を受けるすべてのファイルに適用されます. ステータスコードと考えられるエラー条件の詳細については、"エラー処理 (Error Handling)", セクション 2.2 を参照してください.
リクエストがキャッシュを通過し、Request-URI が 1 つ以上の現在キャッシュされているエンティティを識別する場合、それらのエントリは古い (stale) ものとして扱われるべきです (SHOULD). このメソッドへのレスポンスは、明示的な鮮度情報 (freshness information) (Expires ヘッダーまたは "Cache-Control: max-age" ディレクティブなど) と、Request-URI に一致する Content-Location ヘッダーが含まれている場合にのみキャッシュ可能 (cacheable) です. これは、PATCH レスポンスボディがリソース表現であることを示します. キャッシュされた PATCH レスポンスは、後続の GET および HEAD リクエストへの応答にのみ使用できます. 他のメソッド (PATCH など) への応答に使用してはなりません (MUST NOT).
リクエストに含まれるエンティティヘッダー (entity-headers) は、含まれているパッチドキュメントにのみ適用され、変更されるリソースに適用してはならないことに注意してください (MUST NOT). したがって、Content-Language ヘッダーがリクエストに存在する可能性がありますが、それは (何らかの価値があるとしても) パッチドキュメントに言語があることを意味するだけです. サーバーは、トレース情報 (trace information) として以外、そのようなヘッダーを保存すべきではなく (SHOULD NOT)、PUT リクエストで使用される可能性があるのと同じ方法でそのようなヘッダー値を使用すべきではありません (SHOULD NOT). したがって、この文書は、ヘッダーを通じてドキュメントの Content-Type または Content-Language 値を変更する方法を指定していません. ただし、パッチドキュメントを通じてこの目標を達成するメカニズムを設計することは可能です.
リソースが PATCH で変更できるという保証はありません. さらに、異なるパッチドキュメントフォーマットが異なるタイプのリソースに適しており、すべてのタイプのリソースに適した単一のフォーマットはないと予想されます. したがって、実装がサポートする必要がある単一のデフォルトパッチドキュメントフォーマットはありません. サーバーは、受信したパッチドキュメントがターゲット Request-URI によって識別されるリソースのタイプに適していることを確認しなければなりません (MUST).
クライアントは、PUT ではなく PATCH をいつ使用するかを選択する必要があります. たとえば、パッチドキュメントのサイズが PUT で使用される新しいリソースデータのサイズよりも大きい場合、PATCH ではなく PUT を使用する方が理にかなっている可能性があります. POST との比較はさらに困難です. POST は非常に多様な方法で使用され、サーバーが選択した場合、PUT や PATCH のような操作を含むことができるためです. 操作が予測可能な方法で Request-URI によって識別されるリソースを変更しない場合、PATCH または PUT の代わりに POST を検討すべきです.