要約

  • Accept-Patchは、資源がパッチ文書として受け入れるメディア型を列挙する。存在すればPATCH能力を示すが、呼出し元を認証せず、書込みを許可せず、形式を選ばず、具体的な変更の妥当性も保証しない。
  • 発見、パッチ言語、状態の前提条件、認可は四つの独立した判断である。告知は要求の準備に役立つだけで、残りは実際の要求とその文脈で決めなければならない。

OPTIONS応答にapplication/json-patch+jsonとapplication/merge-patch+jsonが並んでいる。クライアントが知ったのは、この資源が二つのパッチ文法を告知しているということだ。現在のアカウントに編集権があるか、読んだ版がまだ最新か、操作が業務規則に反しないかは分からない。資格情報を受け取ったわけでもない。

誤解は、発見情報の正式な外見から生まれる。サーバーが返し、登録済みの名前を使い、Allowと同じ応答に現れるため、ライブラリは「編集可能」という一つの真偽値にまとめたくなる。しかしRFC 5789は、形式の告知とPATCH要求の認可を別に定めている。

資源の能力と主体の権利

PATCHが必要になったのは、PUTが完全な置換を意味する一方、部分変更には既存状態への指示を記述する文書が必要だからである。対象URIが資源を定め、Content-Typeがパッチ言語を定める。前提条件は観測した状態に処理を結び付け、認証とアクセス制御は主体が行為できるかを決める。

Accept-Patchはその前段にある。値は任意のパラメーターを伴うメディア型のリストである。PATCH対応資源のOPTIONS応答にはこのフィールドを含めるべきであり、どのメソッドへの応答であっても存在すれば、その要求URIの資源でPATCHが許容されることを暗黙に示す。列挙された型は、その資源で受け入れるパッチ文書形式を示す。

ここでの許容は資源のプロトコル能力であり、あらゆる主体への権限ではない。RFC 5789のセキュリティ節は、要求の認可、アクセス制御、認証を別の義務として挙げる。公開GETで形式を告知しながら、匿名PATCHに401や403を返しても矛盾しない。二つのアカウントが同じ一覧を見ても、変更できるフィールドは異なり得る。

AllowにPATCHがあってAccept-Patchがない場合もある。この場合はメソッドだけが告知され、文書形式は告知されていない。逆にAccept-PatchがGETなどの応答にあれば、暗黙のメソッド表示は保たれる。RFC 9110によれば、実際に許されるメソッド集合は各要求時点でオリジンサーバーが定め、動的に変わり得る。発見結果は時点付き観測であって、予約ではない。

メディア型が意味を運ぶ

PATCHには全実装必須の既定文書形式がない。サーバーは、受け取った文書が対象資源に適することを確認しなければならない。検証済みErratum 3169は、この境界を明確にした。PATCH固有の適用方法は要求メディア型によって定まり、汎用application/jsonやapplication/xmlを解析できるだけでパッチ意味論を仮定してはならない。

RFC 6902のapplication/json-patch+jsonは、add、remove、replace、move、copy、testなどを順序付き配列で表す。RFC 7396のapplication/merge-patch+jsonは対象文書に似た形を取り、比較によって追加と置換を決め、nullを既存メンバー削除の特別な記号にする。

両方がJSONを扱っても交換可能ではない。JSON Patchのtestは、操作列の中で一つの仮定を検証できる。Merge Patchはオブジェクト中心の文書には簡潔だが、nullを実値として使う構造や配列の細かな編集には向かない。両方を告知することは、自動変換や優先順位を許可しない。

クライアントはContent-Typeで意図する形式を明示する。SDKが一覧の先頭を機械的に選んだり、既存本文のラベルだけを変えたりしてはいけない。パラメーターも意味を持ち得る。

拒否応答にも告知は置ける

形式が対応済みでも具体的要求は失敗する。RFC 5789は原因を分ける。不正な文書は400、対象が扱わない型は415、構文は正しいが処理不能なら422、存在しない資源にその形式を適用できないなら404、状態や並行処理の衝突なら409、明示した前提条件が偽なら412が候補になる。

415応答にはAccept-Patchを含め、対応形式を知らせるべきだとされる。つまりサーバーは要求を拒否したまま、次の判断材料を渡せる。告知は失敗を成功へ変えず、Content-Typeだけの付替えも許さず、別形式の要求が認証や業務検証を通るとも約束しない。

クライアントは拒否を保持し、形式一覧を提示し、意味を保った新しい文書を作れるかをローカルに判断する。その新規要求には新しい状態と認可判断がある。発見は推測を減らすが、再送命令ではない。

If-Matchは状態を守る

既知の版を前提にするパッチは衝突に弱い。二つのクライアントが同じ版から文書を作れば、後の処理が新状態を壊しかねない。RFC 5789は条件付き要求を推奨し、強いETagをIf-Matchに入れる例を示す。

RFC 9110では、サーバーがメソッド実行前にIf-Matchを強比較で評価する。現在の表現が観測した版と同じときだけ適用する、という条件であり、不一致なら412にできる。サーバーが勝手に再ベースする必要はない。

しかしETagは権限情報ではない。無権限の主体が最新値を知ることも、権限ある主体が古い値を送ることもある。アクセスと状態は二つの検査であり、Accept-Patchはどちらも代替しない。

IANAはPATCHを安全でなく、冪等でもないメソッドとして登録している。個別要求を冪等に設計できる場合はあるが、操作内容次第である。追記の再送と、testで守られた置換の再送は同じではない。形式一覧だけから再試行の性質は分からない。

原子性は実行時の境界

サーバーは変更集合をすべて適用するか、何も適用しない。処理途中の表現を公開してはならず、文書全体を実行できなければ一部変更も残してはならない。

RFC 6902はtest失敗の例で、JSON Patch全体が無変更になると説明する。これは実行契約であって、告知が与える権限ではない。PATCHはアプリケーションの定義により他の資源へ影響する場合もあるため、直接影響を受ける対象を同じコミット境界に置く必要がある。

実装は、認証、対象と操作の認可、Content-Type検証、対応文法の解析、前提条件と業務規則の評価、変更の準備、原子的コミットを順に行える。Accept-Patchを読むだけでは取引もロックも始まらない。

キャッシュは変更後に反応する

RFC 9111は、非安全メソッドへの非エラー応答を受けた経路上キャッシュに、対象URIの保存応答を無効化させる。同一オリジンのLocationやContent-Locationも候補にできるが、異なるオリジンへの無効化は禁止される。

これは実際のPATCHが成功した後の結果である。Accept-Patchを含むOPTIONSは状態を変えず、消去命令にならない。成功後も無効化は要求が通ったキャッシュに限られ、全世界の複製を同期する保証ではない。

署名は告知の完全性を守る

RFC 9421に基づくアプリケーションプロファイルは、Accept-Patchを署名対象にできる。検証により選択した成分の完全性と真正性を確認できるが、書込みのアクセス判断は自動生成されない。

プロファイルは必要成分、鍵、アルゴリズム、信頼方針を定める。別の認可プロトコルが主体、メソッド、対象、内容を結べば効力を持ち得るが、その効力は追加規則から生まれる。暗号は告知を保存し、意味を拡張しない。

監査できるデータモデル

クライアントは、資源URIと観測時刻、AllowまたはAccept-Patchによるメソッド情報、型とパラメーター、パッチを作った基準表現のバリデーター、新規要求の資格情報と方針文脈を分けて持つべきだ。画面上で統合しても、記録では由来を消さない。

サーバーはOPTIONSで比較的安定した能力を示し、PATCH到着時に認証、認可、型検証、文法解析、If-Matchと業務規則の評価、原子的確定を行う。415で代替形式を知らせても、次回成功を保証しない。

試験には、AllowだけにPATCH、GET応答の形式一覧、異なる権限の主体への同じ告知、古いIf-Match、汎用JSON拒否、二つのJSON形式の異なる結果、test失敗後の無変更、署名済み告知の後の403を含める。

現在のRFC 5789 errataには検証済み三件と却下一件がある。5521は204例からContent-Locationと説明を削除するため、旧例を方針根拠にしない。7513は内部リンク訂正であり分類を変えない。却下された3419も規範ではない。

出典