要約

  • RFC 9457では、解決後のtype URIが問題タイプの主要な識別子である。参照先に人向け文書を置けることは、自動取得、規則の取り込み、再試行、権限付与を意味しない。
  • 実装は、実際のHTTPステータス、助言的なstatus、人向けのtitleとdetail、一件を示すinstance、定義済み拡張、効果を許可するローカル方針を別々に扱う必要がある。

ある業務クライアントが既知のエラーを受け取る。typeはHTTPSのアドレスである。クライアントは自動的にそのページを開き、そこに書かれた新しい「解決手順」を読み、前の要求を別の形で再送する。

便利な自己修復に見える。しかし、実際には更新可能な説明ページが、配布済みソフトウェアの判断規則を書き換えている。

問題タイプURIが示したのは、応答がどの意味を主張しているかである。文書は開発者の理解を助けられる。それだけでは応答元を認証せず、最初の処理が失敗したとも証明せず、再実行を安全にせず、利用者の新しい意思も表さない。意味の名前と効果の権限を同じにしてはならない。

URIは多目的なので誤解が生じやすい。抽象概念を識別できる一方、ブラウザーで取得できる場所にも見える。名前解決やHTTP取得が容易であるため、「取得できる」が「取得すべき」に変わり、さらに「読める」が「実行できる」へ変わる。

RFC 9457はここに明確な線を引く。typeは問題タイプを識別するURI参照であり、必要な解決を行ったURIを消費者は主要識別子として使わなければならない。HTTPまたはHTTPSのURIを参照した場合は人間向け文書を得られることが望ましいが、デバッグ機能など開発者へ情報を示す場合を除き、自動的に参照すべきではない。

この構造なら、説明可能性と運用上の独立性が両立する。サービスは長く使える語彙を公開する。クライアントは事前に確認したタイプだけを明示的に扱う。未知のエラーを調べる開発者は意図的に文書を開く。実行時の失敗処理が、毎回文書サーバーへ問い合わせる必要はない。

同じオブジェクトでも役割は異なる

Problem DetailsはJSONの共通形式を提供し、XMLでの対応表現も定義する。しかし、各メンバーの意味と権限は同じではない。

typeは問題の種類を識別する。省略時はabout:blankとなり、HTTPステータス以上の追加意味を持たない。クライアントは通常のステータス処理に戻れるが、説明文から勝手に専用タイプを作ってはならない。

titleはタイプを短く示す人間向け要約である。ローカライズを除けば発生ごとに変えるべきではないが、あくまで助言的である。タイトル文字列で分岐すると、自然な翻訳への改善がプロトコル変更になってしまう。

detailは今回の発生について人が読む説明である。問題の修正を助け、実装のデバッグ情報を漏らさないことが期待される。RFC 9457は、機械情報を得るためにこの文章を解析しないよう求める。数値や項目を安定して扱う必要があるなら、タイプが定義した拡張メンバーに置く。

instanceは個別事例の識別子である。権限のある人が追加情報を取得できるURIの場合もあれば、サーバー側だけに意味のある不透明な値の場合もある。同じタイプの失敗が多数あっても、各事例は別のinstanceを持てる。

外側のHTTPステータスは汎用HTTPソフトウェアが扱う。statusメンバーは生成元が使ったコードを便利のために繰り返す助言値である。途中のプロキシーやキャッシュが外側を変更すれば不一致が生じる。一方だけを正史として消去するより、差異を経路の証拠として残すべきである。

拡張メンバーはタイプ固有の構造化情報を担う。未知の拡張は無視しなければならない。この規則によって、新しい情報が加わっても古いクライアントが突然停止しない。

この役割分担は小さな統治機構である。共通の外形は相互運用性を作り、固有の意味と行動は理解する当事者に残る。

識別はアクセスを内包しない

RFC 3986でいうURIの資源は、取得可能な文書に限られない。サービス、人、関係の種類、抽象概念も識別できる。URI一般構文は、アクセス、更新、置換などの操作を定めない。URIを使うプロトコル要素やデータ形式が操作の意味を与える。

したがって、解決不能なURIでも問題タイプを識別できる。RFC 9457が解決可能なURIを勧めるのは、将来文書を発見できる余地が有用だからであり、エラーのたびに取得する義務を作るためではない。

最初の命名は互換性にも影響する。解決不能な識別子を後から別のHTTPS URIへ交換すると、タイプのアイデンティティーが変わる。表示タイトルが同じでも、厳密比較を行うクライアントには新しいタイプである。初めから管理可能で安定した名前を選べば、実行時依存を作らずに文書を後から整備できる。

相対URIは基底URIに対して解決される。同じ文字列が、異なる応答資源では別の絶対タイプになる可能性がある。RFC 9457が可能な限り絶対URIを勧めるのは、この隠れた分裂を避けるためである。

だからといって、世界中のタイプを一機関が発行する必要はない。APIは自ら管理する名前空間で固有タイプを定義できる。広く同じ意味で再利用できる場合だけ共通登録を使えばよい。必要なのは安定した識別であり、集中所有ではない。

文書ホストを制御経路に入れない

タイプ文書には、意味、代表的ステータス、拡張、解決の選択肢を丁寧に書ける。同時に、そのサイトは停止し、転送され、運営主体が変わり、クライアントとは別周期で更新される。ドメインや発行権限が侵害されれば、URIを変えずに内容だけが置換される。

自動参照は、こうした編集・運用上の変化を本番入力へ変える。失敗中の処理にDNS、ネットワーク、証明書、転送先という依存を追加し、問い合わせ時刻から発生中の問題を外部へ知らせる。取得先を制限しないサーバー実装では、意図しないネットワークへの接続も生み得る。

文書を捨てる必要はない。診断画面に明示的なリンクを出し、開発時に定義を審査し、テスト済みのハンドラーを次のクライアント版に含めればよい。閲覧は意図的な行為になり、ページの変更が既存版の取引規則を暗黙に変更しない。

機械向けの修復先が必要なら、問題タイプは意味を定めた拡張と型付きリンクを使える。RFC 8288はリンク関係の表現を助けるが、リンクは任意メソッドの実行権ではない。認証、認可、送信元、再送安全性、有効期限、利用者の意思は別に確認する。

人向け文書が入金を勧め、拡張が対象口座を指し、認証済み操作が送金を提供することはあり得る。三者が連携しても、最初のURIが支払いを命令したわけではない。

自然言語を隠れた列挙値にしない

detailから金額やエラー分類を抜き出す実装は、最初の一言語では動く。説明が自然な語順に変わり、二つの値を含み、別言語で返されると分岐が変わる。人向け文章を固定して機械を守るのは責任の逆転である。

機械に必要な値は、型の定義に基づく拡張に置く。typeが意味を固定し、拡張が構造を運び、detailは今回の事情を人に説明する。未知の拡張を無視する規則が安全な進化を支える。

titleも機械キーではない。利用者の言語に合わせられることが価値である。プログラムは解決済みURIを比較し、画面は適切な言語のタイトルを表示すればよい。

ただし、既知タイプの一致は真実性を証明しない。侵害されたサーバーも既知URIを送れる。保存された本文は元要求から切り離されることがある。途中でステータスが変わることもある。重要な効果の前には、認証された相手、要求との結び付き、契約版、現在の権限を確かめる。

そして行動そのものの記録を残す。どのタイプと拡張を認識し、どのローカル規則が発火し、誰が承認し、最終結果をどの権威ある系が確認したかを示す。URIは意味の入口であり、因果や権限の領収書ではない。

共通登録は局所語彙を吸収しない

RFC 9457は、一般的で広く使われる問題タイプを再利用するためIANA HTTP Problem Types登録表を設けた。手続はSpecification Requiredであり、専門家は定義の明確さ、仕様要件、コミュニティーの意見を検討する。ベンダー、アプリケーション、個別配備だけに固有の値は登録できない。

これは局所タイプの禁止ではない。特殊な意味を責任あるAPIの近くに置き、私的な規則を世界共通の語彙として見せないための境界である。裏付け文書は安定し自由に読めることが望ましいが、それ自体が標準である必要はない。

IANAのフラグメント接頭辞を使う登録URIは解決できない場合がある。それでも登録行と参照仕様が意味を定める。各エラーでIANAへ接続することは要件ではない。

about:blankは最小例である。HTTPステータス以上の意味を持たず、タイトルはローカライズできる。空白だからといって、クライアントが特別な修復権限を書き込めるわけではない。

登録は安全認証でも全APIへの適合証明でもない。共通の名前を整える仕事と、個別の信頼・行動判断を分ける必要がある。

復旧判断を独立した対象にする

まずクライアントは、実際のHTTPステータス、認証済み相手、要求、解決済みタイプ、instance、既知拡張、受信時刻を保存する。本文statusと外側が違えば、両方を残す。

次に知識を分類する。既知タイプには審査済み定義と対応ハンドラー版がある。未知タイプは安全な既定処理で表示・記録し、未知拡張は無視する。about:blankはステータスの一般則へ戻す。

その後に権限を判定する。再試行はメソッド、冪等性、前の結果を調べる。状態変更は通常の認可を必要とする。instance取得はアクセス制御に従う。タイプを知っているだけでは何も免除されない。

最後に、開発者の発見経路を本番効果から分ける。参照先の送信元やネットワークを制限した道具で文書を開き、変更を審査してからクライアントを更新する。

これはLu Hengの順序に合う。最初に小さな共通仕様を置き、将来の判断を結果を負う現場へ残し、読める情報に基づく自発的な採用を可能にする。各エラーを中央が許可する必要はなく、遠隔ページが全クライアントを統治する必要もない。

出典