1. Einleitung
HTTP [RFC7230] Statuscodes sind manchmal nicht ausreichend, um genügend Informationen über einen Fehler zu übermitteln, um hilfreich zu sein. Während Menschen hinter Webbrowsern über die Natur des Problems mit einem HTML [W3C.REC-html5-20141028] Antworttext informiert werden können, sind nicht-menschliche Verbraucher sogenannter „HTTP-APIs" dies in der Regel nicht.
Diese Spezifikation definiert einfache JSON [RFC7159] und XML [W3C.REC-xml-20081126] Dokumentformate für diesen Zweck. Sie sind so konzipiert, dass sie von HTTP-APIs wiederverwendet werden können, die unterschiedliche, für ihre Bedürfnisse spezifische „Problemtypen (Problem Types)" identifizieren können.
Somit können API-Clients sowohl über die übergeordnete Fehlerklasse (unter Verwendung des Statuscodes) als auch über die feineren Details des Problems (unter Verwendung eines dieser Formate) informiert werden.
Betrachten Sie beispielsweise eine Antwort, die anzeigt, dass das Konto des Clients nicht über ausreichend Guthaben verfügt. Der Statuscode 403 Forbidden könnte als am besten geeignet angesehen werden, da er HTTP-generische Software (wie Client-Bibliotheken, Caches und Proxies) über die allgemeine Semantik der Antwort informiert.
Dies gibt dem API-Client jedoch nicht genügend Informationen darüber, warum die Anfrage verboten wurde, welcher Kontostand gilt oder wie das Problem behoben werden kann. Wenn diese Details im Antworttext in einem maschinenlesbaren Format enthalten sind, kann der Client sie angemessen behandeln; beispielsweise durch Auslösen einer Überweisung von mehr Guthaben auf das Konto.
Diese Spezifikation erreicht dies, indem sie einen bestimmten Problemtyp (z.B. „Guthaben aufgebraucht (out of credit)") mit einem URI [RFC3986] identifiziert; HTTP-APIs können dies tun, indem sie neue URIs unter ihrer Kontrolle benennen oder bestehende wiederverwenden.
Darüber hinaus können Problemdetails andere Informationen enthalten, wie z.B. einen URI, der das spezifische Auftreten des Problems identifiziert (wodurch dem Konzept „Der Zeitpunkt, als Joe letzten Donnerstag nicht genug Guthaben hatte" effektiv ein Identifikator gegeben wird), was für Support- oder forensische Zwecke nützlich sein kann.
Das Datenmodell für Problemdetails ist ein JSON [RFC7159] Objekt; wenn es als JSON-Dokument formatiert wird, verwendet es den Medientyp application/problem+json. Anhang A definiert, wie sie in einem äquivalenten XML-Format ausgedrückt werden, das den Medientyp application/problem+xml verwendet.
Beachten Sie, dass Problemdetails (natürlich) nicht die einzige Möglichkeit sind, die Details eines Problems in HTTP zu übermitteln; wenn die Antwort beispielsweise immer noch eine Darstellung einer Ressource ist, ist es oft vorzuziehen, die relevanten Details im Format dieser Anwendung zu beschreiben. Ebenso gibt es in vielen Situationen einen geeigneten HTTP-Statuscode, der keine zusätzlichen Details erfordert.
Stattdessen besteht das Ziel dieser Spezifikation darin, gemeinsame Fehlerformate für Anwendungen zu definieren, die eines benötigen, damit sie nicht gezwungen sind, ihre eigenen zu definieren, oder schlimmer noch, versucht sind, die Semantik bestehender HTTP-Statuscodes neu zu definieren. Selbst wenn eine Anwendung sich entscheidet, es nicht zur Übermittlung von Fehlern zu verwenden, kann die Überprüfung seines Designs helfen, die Designentscheidungen zu leiten, denen man bei der Übermittlung von Fehlern in einem bestehenden Format gegenübersteht.