Problem Details for HTTP APIs
rfc-editor.org
rfc-editor.org
To properly handle errors, there needs to be an exhaustive enumeration of the types of errors. This is hard to generalize across all applications and this RFC just sidesteps it entirely.
We don't need yet another way to bundle together a bunch of strings nobody ever reads and that applications will have to parse because there's no error code beyond the woefully inadequate HTTP status. If the app dev has to roll their own enumeration scheme and put this application-level error code in an extension, that's no better than just responding with the JSON they already had.
It's covered by the "type" property of the RFC-defined payload. Type is a globally (URL-based) unique value that your application can either match (and handle) or grab full details (GET url) which can be cached. This allows servers to serve new errors to old clients.
Error handling is underserved in most apps and putting it in a standard increases the probability that npm-install-library developers will do it at all.
1. API were ultimately expected to throw a ProblemDetailsException. A response filter would catch and wrap other unexpected throwables into a problem details exception.
2. The resulting exception handler preferred [a/p+j, a/j, a/p+x, a/x, t/h] media type ordering (with abbreviated names), which meant that a browser would get HTML errors while something like curl would get application/problem+json
I considered a XSLT on the XML output, but that just seemed like going for bonus points.
It’d be nice though if JSON:API just referred to problem details and added extensions for the JSON:API specific bits.
> The members data and errors MUST NOT coexist in the same document.
I would have moved them to a single property that is freeform. Makes parsing easier IMO.
more from the authors btw:
which has been approved: https://datatracker.ietf.org/doc/draft-ietf-httpapi-rfc7807b...
(I didn't realise, credit to https://news.ycombinator.com/item?id=35366691)
If you omit the "type", the message has no additional semantics beyond that of the HTTP status code. So this provides a standard for error responses with JSON bodies:
{
"title": "Not Found",
"status": 404,
"detail": "The file you are looking for doesn't exist."
}Section 3.1 https://www.rfc-editor.org/rfc/rfc7807#section-3.1 suggests there's nothing in there that couldn't be done with response headers. A couple of URIs, some strings, and a useless status field. Useless because in reality a client will always have to obey the response status code.
Extensions can be easily done via headers. x-amz-... have paved the path.
Even so, the RFC specifically addresses arbitrary formats, and there’s nothing in it which would preclude headers as one such format.
In case of XML, yes, in case of JSON... where? Extensions?
> Even so, the RFC specifically addresses arbitrary formats, and there’s nothing in it which would preclude headers as one such format.
Yeah, the Appendix B is mightily confusing. It basically says "in case of specific requirements, do as you please":
This specification does not make specific recommendations regarding
embedding problem details in other formats; the appropriate way to
embed them depends both upon the format in use and application of
that format.Yes.
> Yeah, the Appendix B is mightily confusing. It basically says "in case of specific requirements, do as you please"
Yep! The world is your HTTP header oyster.
So basically it does not address anything. I begin to wonder what’s the point of this RFC.
Was it the case “oh, we use this inside of Akamai but some of our clients require some form of a standard so can we please push this one through”?
I mean, surely if you’re going to propose a standard that suppose to address some shortcomings of HTTP, you’d do it so that it can be used by anybody without any dependency other than HTTP itself. No?
If it doesn’t solve a problem you have, it’s okay to recognize that without categorically declaring it doesn’t solve any problems. The point of the RFC is very clearly stated, and its scope is intentionally limited and flexible.
The problem it identifies is a common set of error conditions, and some general ways that those general conditions might carry more detail. The solution proposed is a general way of modeling those, with some proscribed semantics for popular data formats and a less proscribed and very permissive way to incorporate the same approach in any format whatsoever.
> I mean, surely if you’re going to propose a standard that suppose to address some shortcomings of HTTP, you’d do it so that it can be used by anybody without any dependency other than HTTP itself. No?
They did do that. If you’re so insistent that it use headers only and no semantics specified outside of HTTP, you must already know that the Link header has all of the structural semantics you’d need to implement the same data structures. You’d still need to parse the header, but again if you’re so invested in that particular approach you probably already have a solution to that.
If your expectation is that this RFC uses only HTTP headers but comes with built in semantics for arbitrary structured data within HTTP headers, your demand is impossible to satisfy. HTTP headers are inherently a dictionary relation of strings to strings, until HTTP itself is modified to accommodate something more sophisticated. And if anyone tried to make that change it would face far more backlash than “feel free to pack whatever data into that dictionary you want, if that’s your thang”.
- address common cases with flexibility for domain specific minutiae
- explicitly call out that there are cases where it’s either redundant or insufficient
I was also struck by how `type` feels very reminiscent of XML namespace URIs, but it’s great that there’s a SHOULD recommendation that the URIs resolve to something meaningful in resolving problems.
Overall it’s not an earth shattering idea, but it seems like a pretty good baseline approach to solving something that’s often either neglected or reinvented.
The only thing I don't like here is the "type" parameter and how its expected to be an URI. That will only hamper implementation, considering most API documentation isn't distributed as individual error pages. Most of the time you either have a PDF document (for private APIs), a single big HTML page (which to be fair, can be anchored) or in some cases, physical documentation.
Personally I'd just have allowed type to be a simple string that informs the machine about the type of exception that occurred, and expect people implementing the API to figure out what that means (ie. Through external documentation) instead of making it a URI.
The out of credit example would have a "type" of "OutOfCreditException" in my suggestion, of course adjustable by whatever is preferred.
This RFC is just a slightly pointless standardization that has one weird thing in it that nobody actually does, which to be fair "here's what were all doing but slightly different, so get to work" can describe a lot of RFCs.
You’re free to use whatever URI suits your purpose, like a URN or maybe even your on scheme. All the spec asks is that it’s a URI which is a wide and flexible range of identifiers, only a subset of which actually point somewhere.
(I’m simplifying, of course, but I think it’ll be a decent generalisation.)
[1] https://github.com/googleapis/googleapis/blob/1c8a25ab153eef...
HTTP isn't really only about HyperText, nor only about HTML -- it's about everything.
For comparison, look at FTP: it really is about the file transfer, you can tell that that is its application domain. Then look back at HTTP... yep, a generic request-response protocol, suitable for building pretty much anything else on top it.
Basically it’s format-agnostic, but it covers the two most common/likely scenarios. IMO that’s sensible enough, but it’s not ideal how much the format-agnostic aspect is deemphasized.