This document defines a "problem detail" to carry machine-readable details of errors in HTTP response content to avoid the need to define new error response formats for HTTP APIs.
This document obsoletes RFC 7807.
Context is whatever makes sense to provide to a consumer to help them debug it or respond to it - the same basic idea as in the rfc under details. IMO, it can’t easily be generalized. Some APIs may have context to provide, others may not. These could be validation errors in a structured format, or backoff timings in the case of a 429.
Success is something that you can sniff for after deserializing, as IIRC Fetch API will not throw except for a network errors, even in the event of a 4XX or 5XX.
Consider something like:if(!obj.error_code){} vs if(obj.success){ }. Certainly, you could consolidate the error_code and success member, but with the sloppy truthiness of testing in Javascript, including something like that as a standard part of all responses may make sense.
No> Context is whatever makes sense to provide to a consumer to help them debug it or respond to it
So it’s both optional and unspecified. This means it can’t be parsed or relied upon, specially by consumers. It’s useless.
the same basic idea as in the rfc under details.
No, it isn’t. Contrary to your ad-hoc format, RFC9457 specifies exactly the data type of detail and what’s its purpose. This allows third parties to reliably consume resources that comply with RFC9457 while your ad-hoc format leaves clients no option other than to ignore it.
IMO, it can’t easily be generalized. Some APIs may have context to provide, others may not.
It matters nothing what services can produce. What matters is whether clients can consume it. Your ad-hoc format fails to specify this field, which is optional, and thus leaves no option other than to ignore it. It’s unusable.
Success is something that you can sniff for after deserializing, as IIRC Fetch API will not throw except for a network errors, even in the event of a 4XX or 5XX.
What the Fetch API does or does not do is irrelevant. The responsibility of putting together a response and generating the resource shipped with it lies exclusicely in your service. If it outputs a resource that is unable to tell clients what went on, that’s a problem cause by both how your service is designed and the ad-hoc format it outputs.
The main take is that RFC9457 is well specified and covers basic usecases, while your ad-hoc format is broken by design. Thus when you describe the RFC as “overwrought”, you’re actually expressing the half-baked approach you took.
Sorry, I didn’t mean to reference the detail member, I meant “extension members” as defined in the RFC.
In the RFC, they are outlined as top-level elements. In the version I proposed, these are bundled up inside of an optional context member. This can be useful in making the serialization and deserialization process a little bit easier to implement in languages that support generics without the need to subclass for the common elements. The RFC specifically defines “extension members” as optional. The key difference is that in what I was describing, they’d be bundled into one object, rather than being siblings of the top-level response.
It also side-steps any future top-level reserved keyword collisions by keeping “user-defined” members a separate box.
You seem to be laboring under the notion that this spec produces something that can be entirely negotiated by generic clients, but I don’t see that at all. Even for “trivial” examples (multiple validation errors, or rate-limiting thottling), clients would need to implement specialized handlers, which is only vaguely touched upon by the need to have a “problem registry”.
And, like it or not, considering how easy or messy it is for a downstream client to consume a result is actually an important part of API design. I don’t see how considering the browser, javascript, and the Fetch API behavior aren’t relevent considerations when we’re talking about extending HTTP with JSON responses.
Did you author this RFC? I don’t exactly understand why you seem to be taking the criticism personally.
Context is whatever makes sense to provide to a consumer to help them debug it or respond to it - the same basic idea as in the rfc under
details. IMO, it can’t easily be generalized. Some APIs may have context to provide, others may not. These could be validation errors in a structured format, or backoff timings in the case of a 429.Success is something that you can sniff for after deserializing, as IIRC Fetch API will not throw except for a network errors, even in the event of a 4XX or 5XX.
Consider something like:
if(!obj.error_code){}vsif(obj.success){ }. Certainly, you could consolidate theerror_codeandsuccessmember, but with the sloppy truthiness of testing in Javascript, including something like that as a standard part of all responses may make sense.No> Context is whatever makes sense to provide to a consumer to help them debug it or respond to it
So it’s both optional and unspecified. This means it can’t be parsed or relied upon, specially by consumers. It’s useless.
No, it isn’t. Contrary to your ad-hoc format, RFC9457 specifies exactly the data type of
detailand what’s its purpose. This allows third parties to reliably consume resources that comply with RFC9457 while your ad-hoc format leaves clients no option other than to ignore it.It matters nothing what services can produce. What matters is whether clients can consume it. Your ad-hoc format fails to specify this field, which is optional, and thus leaves no option other than to ignore it. It’s unusable.
What the Fetch API does or does not do is irrelevant. The responsibility of putting together a response and generating the resource shipped with it lies exclusicely in your service. If it outputs a resource that is unable to tell clients what went on, that’s a problem cause by both how your service is designed and the ad-hoc format it outputs.
The main take is that RFC9457 is well specified and covers basic usecases, while your ad-hoc format is broken by design. Thus when you describe the RFC as “overwrought”, you’re actually expressing the half-baked approach you took.
Sorry, I didn’t mean to reference the
detailmember, I meant “extension members” as defined in the RFC.In the RFC, they are outlined as top-level elements. In the version I proposed, these are bundled up inside of an optional
contextmember. This can be useful in making the serialization and deserialization process a little bit easier to implement in languages that support generics without the need to subclass for the common elements. The RFC specifically defines “extension members” as optional. The key difference is that in what I was describing, they’d be bundled into one object, rather than being siblings of the top-level response.It also side-steps any future top-level reserved keyword collisions by keeping “user-defined” members a separate box.
You seem to be laboring under the notion that this spec produces something that can be entirely negotiated by generic clients, but I don’t see that at all. Even for “trivial” examples (multiple validation errors, or rate-limiting thottling), clients would need to implement specialized handlers, which is only vaguely touched upon by the need to have a “problem registry”.
And, like it or not, considering how easy or messy it is for a downstream client to consume a result is actually an important part of API design. I don’t see how considering the browser, javascript, and the Fetch API behavior aren’t relevent considerations when we’re talking about extending HTTP with JSON responses.
Did you author this RFC? I don’t exactly understand why you seem to be taking the criticism personally.
deleted by creator