When ASP.NET Core 2.1 came out, there’s was a relatively brief announcement about new support for “Problem Details” (RFC 7807).
In this release we added support for RFC 7808 – Problem Details for HTTP APIs as a standardized format for returning machine readable error responses from HTTP APIs.
If you just want a better explanation of problem details, fear not. I read the documentation for you.
Problem Details is nothing more than a standard JSON format and content type. Here’s a sample from the documentation:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
HTTP/1.1 403 Forbidden Content-Type: application/problem+json Content-Language: en { "type": "https://example.com/probs/out-of-credit", "title": "You do not have enough credit.", "detail": "Your current balance is 30, but that costs 50.", "instance": "/account/12345/msgs/abc", "balance": 30, "accounts": ["/account/12345", "/account/67890"] } |
The first three lines indicate the headers returned from the server. 403 is just a sample code. Your API can return any code it needs to return for a given error condition. The Content-Type is important, though.
The only problem details-specific elements for in this example are “type”, “title”, “detail”, and “instance”.
“balance” and “accounts” are custom properties. That means you can include any additional data you want in your problem details.
Honestly, it’s worth digging into the documentation if you want to know more, but here’s what I think is the most important bit:
3.1. Members of a Problem Details Object
A problem details object can have the following members:
o “type” (string) – A URI reference [RFC3986] that identifies the
problem type. This specification encourages that, when
dereferenced, it provide human-readable documentation for the
problem type (e.g., using HTML [W3C.REC-html5-20141028]). When
this member is not present, its value is assumed to be
“about:blank”.o “title” (string) – A short, human-readable summary of the problem
type. It SHOULD NOT change from occurrence to occurrence of the
problem, except for purposes of localization (e.g., using
proactive content negotiation; see [RFC7231], Section 3.4).o “status” (number) – The HTTP status code ([RFC7231], Section 6)
generated by the origin server for this occurrence of the problem.o “detail” (string) – A human-readable explanation specific to this
occurrence of the problem.o “instance” (string) – A URI reference that identifies the specific
occurrence of the problem. It may or may not yield further
information if dereferenced.Consumers MUST use the “type” string as the primary identifier for
the problem type; the “title” string is advisory and included only
for users who are not aware of the semantics of the URI and do not
have the ability to discover them (e.g., offline log analysis).
Consumers SHOULD NOT automatically dereference the type URI.The “status” member, if present, is only advisory; it conveys the
HTTP status code used for the convenience of the consumer.
Generators MUST use the same status code in the actual HTTP response,
to assure that generic HTTP software that does not understand this
format still behaves correctly. See Section 5 for further caveats
regarding its use.Consumers can use the status member to determine what the original
status code used by the generator was, in cases where it has been
changed (e.g., by an intermediary or cache), and when message bodies
persist without HTTP information. Generic HTTP software will still
use the HTTP status code.The “detail” member, if present, ought to focus on helping the client
correct the problem, rather than giving debugging information.Consumers SHOULD NOT parse the “detail” member for information;
extensions are more suitable and less error-prone ways to obtain such
information.Note that both “type” and “instance” accept relative URIs; this means
that they must be resolved relative to the document’s base URI, as
per [RFC3986], Section 5
