4. Defining New Problem Types (新しい問題タイプの定義)
HTTP API がエラー条件を示すレスポンスを定義する必要がある場合、新しい問題タイプを定義することによってそれを行うことが適切である可能性があります。
そうする前に、それらが何に適しているか、そして何を他のメカニズムに任せるべきかを理解することが重要です。
問題詳細は基礎となる実装のデバッグツールではありません。むしろ、それらは HTTP インターフェース自体についてより詳細を公開する方法です。新しい問題タイプの設計者は、セキュリティ考慮事項(セクション 5)、特にエラーメッセージを通じて実装内部を公開することによって攻撃ベクトルを公開するリスクを慎重に考慮する必要があります。
同様に、真に汎用的な問題 -- つまり、Web 上の任意のリソースに潜在的に適用される可能性のある条件 -- は、通常、プレーンなステータスコードとして表現する方が良いです。例えば、「書き込みアクセス禁止」問題はおそらく不要です。なぜなら、PUT リクエストに対する 403 Forbidden ステータスコードは自明だからです。
最後に、アプリケーションは、すでに定義している形式でエラーを運ぶためのより適切な方法を持っているかもしれません。問題詳細は、新しい「フォルト (fault)」または「エラー (error)」ドキュメント形式を確立する必要性を回避することを意図しており、既存のドメイン固有の形式を置き換えることを意図していません。
とはいえ、HTTP コンテンツネゴシエーションを使用して既存の HTTP API に問題詳細のサポートを追加することは可能です(例えば、Accept リクエストヘッダーを使用してこの形式への選好を示す。[RFC7231], Section 5.3.2 参照)。
新しい問題タイプ定義は以下を文書化しなければなりません (MUST):
-
type URI(通常、「http」または「https」スキームを使用)、
-
それを適切に記述する title(短く考える)、および
-
それと共に使用される HTTP ステータスコード。
問題タイプ定義は、適切な状況で Retry-After レスポンスヘッダー([RFC7231], Section 7.1.3)の使用を指定してもよい (MAY)。
問題の type URI は、問題を解決する方法を説明する HTML [W3C.REC-html5-20141028] ドキュメントに解決すべきです (SHOULD)。
問題タイプ定義は、問題詳細オブジェクトに追加のメンバーを指定してもよい (MAY)。例えば、拡張は、機械が問題を解決するために使用できる別のリソースへの型付きリンク [RFC5988] を使用する可能性があります。
そのような追加のメンバーが定義される場合、その名前は文字(ALPHA、[RFC5234], Appendix B.1 による)で始まるべきであり (SHOULD)、ALPHA、DIGIT([RFC5234], Appendix B.1)、および「_」の文字で構成されるべきであり (SHOULD)(JSON 以外の形式でシリアル化できるように)、それらは 3 文字以上であるべきです (SHOULD)。
4.1. 例 (Example)
例えば、オンラインショッピングカートの HTTP API を公開している場合、ユーザーがクレジット不足である(上記の例)ため購入できないことを示す必要があるかもしれません。
この情報を収容できるアプリケーション固有の形式がすでにある場合、それを行うのがおそらく最善です。しかし、そうでない場合、問題詳細形式の 1 つを使用することを検討するかもしれません -- API が JSON ベースの場合は JSON、その形式を使用する場合は XML。
そうするために、あなたの目的に適した、すでに定義された type URI を探すかもしれません。利用可能な場合、その URI を再利用できます。
利用可能でない場合、新しい type URI(あなたの管理下にあり、時間の経過とともに安定しているべき)、適切な title、およびそれと共に使用される HTTP ステータスコードを作成して文書化することができ、それが何を意味し、どのように処理されるべきかと共に。
要約すると: instance URI は常に問題の特定の発生を識別します。一方、type URI は、問題タイプの適切な記述が他の場所で既に利用可能な場合は再利用できますし、新しい問題タイプのために作成することもできます。
4.2. 事前定義された問題タイプ (Predefined Problem Types)
本仕様は、問題タイプとして 1 つの URI の使用を予約します:
about:blank URI [RFC6694] は、問題タイプとして使用される場合、問題が HTTP ステータスコードのセマンティクス以外に追加のセマンティクスを持たないことを示します。
about:blank が使用される場合、title はそのコードの推奨 HTTP ステータスフレーズと同じであるべきです (SHOULD)(例えば、404 の「Not Found」など)。ただし、クライアントの設定に合わせてローカライズされてもよい (MAY)(Accept-Language リクエストヘッダーで表現)。
「type」メンバーがどのように定義されているか(セクション 3.1)によれば、about:blank URI はそのメンバーのデフォルト値であることに注意してください。したがって、明示的な「type」メンバーを持たない問題詳細オブジェクトは暗黙的にこの URI を使用します。