4. Defining New Problem Types (Definition neuer Problemtypen)

Wenn eine HTTP-API eine Antwort definieren muss, die eine Fehlerbedingung anzeigt, kann es angemessen sein, dies durch Definition eines neuen Problemtyps zu tun.

Bevor Sie dies tun, ist es wichtig zu verstehen, wofür sie gut sind und was besser anderen Mechanismen überlassen werden sollte.

Problem Details sind kein Debugging-Tool für die zugrunde liegende Implementierung; sie sind vielmehr ein Mittel, um mehr Details über die HTTP-Schnittstelle selbst offenzulegen. Designer neuer Problemtypen sollten Sicherheitsüberlegungen (Abschnitt 5) sorgfältig berücksichtigen, insbesondere das Risiko, Angriffsvektoren durch die Offenlegung interner Implementierungsdetails durch Fehlermeldungen freizulegen.

Ebenso sind wirklich generische Probleme -- d.h. Bedingungen, die für jede Ressource im Web gelten könnten -- im Allgemeinen besser als einfache Statuscodes ausgedrückt. Beispielsweise ist ein "write access disallowed"-Problem wahrscheinlich unnötig, da ein 403 Forbidden-Statuscode als Antwort auf eine PUT-Anfrage selbsterklärend ist.

Schließlich könnte eine Anwendung eine angemessenere Möglichkeit haben, einen Fehler in einem bereits definierten Format zu übertragen. Problem Details sollen die Notwendigkeit vermeiden, neue "fault"- oder "error"-Dokumentformate einzurichten, nicht domänenspezifische bestehende Formate ersetzen.

Das heißt, es ist möglich, Unterstützung für Problem Details zu bestehenden HTTP-APIs hinzuzufügen, indem HTTP-Inhaltsverhandlung verwendet wird (z.B. unter Verwendung des Accept-Anforderungsheaders, um eine Präferenz für dieses Format anzugeben; siehe Abschnitt 12.5.1 von [HTTP]).

Neue Problemtypdefinitionen MÜSSEN dokumentieren:

1. eine Typ-URI (typischerweise mit dem Schema "http" oder "https")

2. einen Titel, der ihn angemessen beschreibt (denken Sie kurz)

3. den HTTP-Statuscode, mit dem er verwendet werden sollte

Problemtypdefinitionen KÖNNEN die Verwendung des Retry-After-Antwortheaders (Abschnitt 10.2.3 von [HTTP]) unter geeigneten Umständen spezifizieren.

Eine Problemtyp-URI SOLLTE zu HTML [HTML5]-Dokumentation auflösen, die erklärt, wie das Problem behoben werden kann.

Eine Problemtypdefinition KANN zusätzliche Mitglieder im Problem Details-Objekt spezifizieren. Beispielsweise könnte eine Erweiterung typisierte Links [WEB-LINKING] zu einer anderen Ressource verwenden, die Maschinen zur Behebung des Problems verwenden können.

Wenn solche zusätzlichen Mitglieder definiert werden, SOLLTEN ihre Namen mit einem Buchstaben (ALPHA, gemäß [ABNF], Anhang B.1) beginnen und SOLLTEN Zeichen von ALPHA, DIGIT ([ABNF], Anhang B.1) und "_" umfassen (damit sie in andere Formate als JSON serialisiert werden können), und sie SOLLTEN drei Zeichen oder mehr haben.

4.1. Example (Beispiel)

Wenn Sie beispielsweise eine HTTP-API für Ihren Online-Einkaufswagen veröffentlichen, müssen Sie möglicherweise anzeigen, dass der Benutzer nicht genug Guthaben hat (unser obiges Beispiel) und daher den Kauf nicht tätigen kann.

Wenn Sie bereits ein anwendungsspezifisches Format haben, das diese Informationen aufnehmen kann, ist es wahrscheinlich am besten, dies zu tun. Wenn Sie dies jedoch nicht haben, könnten Sie eines der Problem Details-Formate verwenden -- JSON, wenn Ihre API JSON-basiert ist, oder XML, wenn sie dieses Format verwendet.

Um dies zu tun, könnten Sie im Register (Abschnitt 4.2) nach einer bereits definierten Typ-URI suchen, die Ihren Anforderungen entspricht. Wenn eine verfügbar ist, können Sie diese URI wiederverwenden.

Wenn keine verfügbar ist, könnten Sie eine neue Typ-URI erstellen und dokumentieren (die unter Ihrer Kontrolle und im Laufe der Zeit stabil sein sollte), einen geeigneten Titel und den HTTP-Statuscode, mit dem sie verwendet wird, sowie was sie bedeutet und wie sie behandelt werden sollte.

4.2. Registered Problem Types (Registrierte Problemtypen)

Diese Spezifikation definiert das Register "HTTP Problem Types" für gemeinsame und weit verbreitete Problemtyp-URIs, um die Wiederverwendung zu fördern.

Die Richtlinie für dieses Register ist Specification Required, gemäß [RFC8126], Abschnitt 4.6.

Bei der Bewertung von Anfragen sollte(n) der/die benannte(n) Expert(en) Feedback von der Community berücksichtigen, wie gut der Problemtyp definiert ist und die Anforderungen dieser Spezifikation. Anbieterspezifische, anwendungsspezifische und bereitstellungsspezifische Werte können nicht registriert werden. Spezifikationsdokumente müssen auf stabile und frei verfügbare Weise veröffentlicht werden (idealerweise mit einer URL lokalisiert), müssen aber nicht unbedingt Standards sein.

Registrierungen KÖNNEN das Präfix "https://iana.org/assignments/http-problem-types#" für die Typ-URI verwenden. Beachten Sie, dass diese URIs möglicherweise nicht aufgelöst werden können.

Die folgende Vorlage sollte für Registrierungsanfragen verwendet werden:

Type URI: [eine URI für den Problemtyp]
Title: [eine kurze Beschreibung des Problemtyps]
Recommended HTTP status code: [welcher Statuscode am besten mit dem Typ verwendet wird]
Reference: [zu einer Spezifikation, die den Typ definiert]

Siehe das Register unter https://iana.org/assignments/http-problem-types für Details darüber, wohin Registrierungsanfragen gesendet werden sollen.

4.2.1. about:blank

Diese Spezifikation registriert einen Problemtyp, "about:blank", wie folgt.

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

Die "about:blank"-URI [ABOUT], wenn sie als Problemtyp verwendet wird, zeigt an, dass das Problem keine zusätzliche Semantik über die des HTTP-Statuscodes hinaus hat.

Wenn "about:blank" verwendet wird, SOLLTE der Titel derselbe sein wie die empfohlene HTTP-Statusphrase für diesen Code (z.B. "Not Found" für 404 usw.), obwohl er KANN lokalisiert werden, um den Client-Präferenzen zu entsprechen (ausgedrückt mit dem Accept-Language-Anforderungsheader).

Bitte beachten Sie, dass gemäß der Definition des "type"-Mitglieds (Abschnitt 3.1) die "about:blank"-URI der Standardwert für dieses Mitglied ist. Daher verwendet jedes Problem Details-Objekt, das kein explizites "type"-Mitglied trägt, implizit diese URI.