メインコンテンツまでスキップ

4. Defining New Problem Types (新しい問題タイプの定義)

HTTP API がエラー条件を示すレスポンスを定義する必要がある場合, 新しい問題タイプを定義することによってそれを行うことが適切な場合があります。

そうする前に, それらが何に適しているか, 何を他のメカニズムに任せるべきかを理解することが重要です。

問題詳細は基礎となる実装のデバッグツールではありません。むしろ, HTTP インターフェース自体に関するより詳細な情報を公開する方法です。新しい問題タイプの設計者は, セキュリティに関する考慮事項 (セクション 5) を慎重に考慮する必要があります。特に, エラーメッセージを通じて実装の内部を公開することによって攻撃ベクトルを公開するリスクがあります。

同様に, 真に汎用的な問題 -- すなわち, Web 上の任意のリソースに適用される可能性のある条件 -- は通常, プレーンなステータスコードとして表現する方が良いです。例えば, "write access disallowed" 問題はおそらく不要です。なぜなら, PUT リクエストに対する 403 Forbidden ステータスコードは自明だからです。

最後に, アプリケーションは既に定義している形式でエラーを運ぶより適切な方法を持っているかもしれません。問題詳細は, 新しい "fault" または "error" ドキュメント形式を確立する必要性を回避することを目的としており, 既存のドメイン固有の形式を置き換えることを目的としていません。

とはいえ, HTTP コンテンツネゴシエーションを使用して既存の HTTP API に問題詳細のサポートを追加することは可能です (例えば, Accept リクエストヘッダーを使用してこの形式への優先を示す。[HTTP] のセクション 12.5.1 を参照)。

新しい問題タイプ定義は以下を文書化しなければなりません (MUST):

  1. type URI (通常, "http" または "https" スキームを持つ)

  2. それを適切に説明する title (短く考える)

  3. それと一緒に使用される HTTP ステータスコード

問題タイプ定義は, 適切な状況で Retry-After レスポンスヘッダー ([HTTP] のセクション 10.2.3) の使用を指定してもかまいません (MAY)。

問題タイプ URI は, 問題の解決方法を説明する HTML [HTML5] ドキュメントに解決すべきです (SHOULD)。

問題タイプ定義は, 問題詳細オブジェクトに追加のメンバーを指定してもかまいません (MAY)。例えば, 拡張は, マシンが問題を解決するために使用できる別のリソースへの型付きリンク [WEB-LINKING] を使用する場合があります。

そのような追加メンバーが定義されている場合, その名前は文字 (ALPHA, [ABNF] の付録 B.1 による) で始まるべきであり (SHOULD), ALPHA, DIGIT ([ABNF] の付録 B.1), および "_" (JSON 以外の形式でシリアライズできるように) の文字で構成されるべきであり (SHOULD), 3 文字以上であるべきです (SHOULD)。

4.1. Example (例)​

例えば, オンラインショッピングカートの HTTP API を公開している場合, ユーザーのクレジットが不足していること (上記の例) を示す必要があり, したがって購入できない可能性があります。

この情報を収容できるアプリケーション固有の形式が既にある場合は, それを行うのがおそらく最善です。ただし, そうでない場合は, 問題詳細形式のいずれかを使用する可能性があります -- API が JSON ベースの場合は JSON, その形式を使用する場合は XML。

そうするために, あなたの目的に適した既に定義された type URI をレジストリ (セクション 4.2) で探すかもしれません。利用可能なものがあれば, その URI を再利用できます。

利用可能なものがない場合, 新しい type URI (あなたの管理下にあり, 時間の経過とともに安定しているべき), 適切な title, それと一緒に使用される HTTP ステータスコード, そしてそれが何を意味し, どのように処理されるべきかを作成して文書化できます。

4.2. Registered Problem Types (登録された問題タイプ)​

この仕様は, 再利用を促進するために, 一般的で広く使用される問題タイプ URI のための "HTTP Problem Types" レジストリを定義します。

このレジストリのポリシーは, [RFC8126] のセクション 4.6 に従って Specification Required です。

リクエストを評価する際, 指定された専門家はコミュニティのフィードバック, 問題タイプがどれだけよく定義されているか, およびこの仕様の要件を考慮すべきです。ベンダー固有, アプリケーション固有, およびデプロイメント固有の値は登録できません。仕様ドキュメントは安定した自由に利用可能な方法で公開されるべきです (理想的には URL で配置) が, 標準である必要はありません。

登録は, type URI にプレフィックス "https://iana.org/assignments/http-problem-types#" を使用してもかまいません (MAY)。これらの URI は解決できない可能性があることに注意してください。

登録リクエストには次のテンプレートを使用すべきです:

Type URI: [問題タイプの URI]
Title: [問題タイプの簡単な説明]
Recommended HTTP status code: [タイプと一緒に使用するのに最も適切なステータスコード]
Reference: [タイプを定義する仕様]

登録リクエストを送信する場所の詳細については, https://iana.org/assignments/http-problem-types のレジストリを参照してください。

4.2.1. about:blank​

この仕様は, 次のように 1 つの問題タイプ "about:blank" を登録します。

Type URI: about:blank
Title: See HTTP Status Code
Recommended HTTP status code: N/A
Reference: RFC 9457

"about:blank" URI [ABOUT] が問題タイプとして使用される場合, 問題は HTTP ステータスコードのもの以外に追加のセマンティクスを持たないことを示します。

"about:blank" が使用される場合, title はそのコードの推奨 HTTP ステータスフレーズと同じであるべきです (SHOULD) (例: 404 の場合は "Not Found" など)。ただし, クライアントの設定 (Accept-Language リクエストヘッダーで表現される) に合わせてローカライズしてもかまいません (MAY)。

"type" メンバーの定義方法 (セクション 3.1) によれば, "about:blank" URI はそのメンバーのデフォルト値であることに注意してください。したがって, 明示的な "type" メンバーを持たない問題詳細オブジェクトは暗黙的にこの URI を使用します。

に最終更新