4. Definition neuer Problemtypen
Wenn eine HTTP-API eine Antwort definieren muss, die eine Fehlerbedingung anzeigt, könnte es angemessen sein, dies durch Definition eines neuen Problemtyps zu tun.
Bevor dies geschieht, ist es wichtig zu verstehen, wofür sie gut sind und was besser anderen Mechanismen überlassen wird.
Problemdetails sind kein Debugging-Tool für die zugrunde liegende Implementierung; vielmehr sind sie eine Möglichkeit, mehr Details über die HTTP-Schnittstelle selbst offenzulegen. Designer neuer Problemtypen müssen die Sicherheitsüberlegungen (Abschnitt 5) sorgfältig berücksichtigen, insbesondere das Risiko, Angriffsvektoren durch Offenlegung von Implementierungsdetails durch Fehlermeldungen offenzulegen.
Ebenso werden wirklich generische Probleme -- d.h. Bedingungen, die potenziell auf jede Ressource im Web zutreffen könnten -- normalerweise besser als einfache Statuscodes ausgedrückt. Zum Beispiel ist ein Problem „Schreibzugriff verweigert" wahrscheinlich unnötig, da ein Statuscode 403 Forbidden als Antwort auf eine PUT-Anfrage selbsterklärend ist.
Schließlich könnte eine Anwendung eine geeignetere Möglichkeit haben, einen Fehler in einem Format zu übertragen, das sie bereits definiert. Problemdetails sind dazu gedacht, die Notwendigkeit zu vermeiden, neue „Fehler"- oder „Error"-Dokumentformate zu etablieren, nicht um bestehende domänenspezifische Formate zu ersetzen.
Das heißt, es ist möglich, Unterstützung für Problemdetails zu bestehenden HTTP-APIs mittels HTTP-Inhaltsverhandlung hinzuzufügen (z.B. unter Verwendung des Accept-Request-Headers, um eine Präferenz für dieses Format anzuzeigen; siehe [RFC7231], Section 5.3.2).
Neue Problemtypdefinitionen müssen (MUST) dokumentieren:
-
einen Typ-URI (typischerweise mit dem Schema „http" oder „https"),
-
einen title, der ihn angemessen beschreibt (denken Sie kurz), und
-
den HTTP-Statuscode, mit dem er verwendet werden soll.
Problemtypdefinitionen können (MAY) die Verwendung des Retry-After-Antwortheaders ([RFC7231], Section 7.1.3) unter geeigneten Umständen spezifizieren.
Der Typ-URI eines Problems sollte (SHOULD) zu HTML [W3C.REC-html5-20141028] Dokumentation auflösen, die erklärt, wie das Problem behoben werden kann.
Eine Problemtypdefinition kann (MAY) zusätzliche Mitglieder am Problemdetails-Objekt spezifizieren. Zum Beispiel könnte eine Erweiterung typisierte Links [RFC5988] zu einer anderen Ressource verwenden, die von Maschinen zur Behebung des Problems verwendet werden kann.
Wenn solche zusätzlichen Mitglieder definiert werden, sollten (SHOULD) ihre Namen mit einem Buchstaben beginnen (ALPHA, gemäß [RFC5234], Appendix B.1) und sollten (SHOULD) aus Zeichen von ALPHA, DIGIT ([RFC5234], Appendix B.1) und „_" bestehen (damit es in anderen Formaten als JSON serialisiert werden kann), und sie sollten (SHOULD) drei Zeichen oder länger sein.
4.1. Beispiel (Example)
Wenn Sie beispielsweise eine HTTP-API für Ihren Online-Warenkorb veröffentlichen, müssen Sie möglicherweise anzeigen, dass der Benutzer kein Guthaben mehr hat (unser Beispiel von oben) 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 jedoch keins haben, könnten Sie erwägen, eines der Problemdetails-Formate zu verwenden -- JSON, wenn Ihre API JSON-basiert ist, oder XML, wenn sie dieses Format verwendet.
Dazu könnten Sie nach einem bereits definierten Typ-URI suchen, der Ihren Zwecken dient. Wenn einer verfügbar ist, können Sie diesen URI wiederverwenden.
Wenn keiner verfügbar ist, könnten Sie einen neuen Typ-URI erstellen und dokumentieren (der unter Ihrer Kontrolle und zeitlich stabil sein sollte), einen geeigneten title und den HTTP-Statuscode, mit dem er verwendet wird, zusammen mit dem, was er bedeutet und wie er behandelt werden sollte.
Zusammenfassend: Ein Instance-URI identifiziert immer ein spezifisches Auftreten eines Problems. Andererseits können Typ-URIs wiederverwendet werden, wenn eine angemessene Beschreibung eines Problemtyps bereits anderswo verfügbar ist, oder sie können für neue Problemtypen erstellt werden.
4.2. Vordefinierte Problemtypen (Predefined Problem Types)
Diese Spezifikation reserviert die Verwendung eines URI als Problemtyp:
Der URI about:blank [RFC6694] zeigt, wenn er als Problemtyp verwendet wird, an, dass das Problem keine zusätzliche Semantik über die des HTTP-Statuscodes hinaus hat.
Wenn about:blank verwendet wird, sollte (SHOULD) der title derselbe sein wie die empfohlene HTTP-Statusphrase für diesen Code (z.B. „Not Found" für 404 usw.), obwohl er lokalisiert werden kann (MAY), um den Clientpräferenzen zu entsprechen (ausgedrückt mit dem Accept-Language-Request-Header).
Bitte beachten Sie, dass gemäß der Definition des „type"-Mitglieds (Abschnitt 3.1) der URI about:blank der Standardwert für dieses Mitglied ist. Folglich verwendet jedes Problemdetails-Objekt, das kein explizites „type"-Mitglied trägt, implizit diesen URI.