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.
If both success and error responses include the success field, then that can be a common discriminator between bodies of successful responses and bodies of error responses. Where this adds value beyond the request’s status code, I’m not sure. Maybe it’s useful in aggregated responses where partial successes are allowed (like POSTing a batch of objects)?
Your format looks half baked and not thought all he way the way through.
This does seem a bit heavily worded. There’s likely a reason they originally chose and continue to use that format, and it could be as simple as “all our other APIs use this format” or similar. There’s more to choosing a response schema than what is theoretically the most efficient way of communicating the information.
Thanks, and you are basically correct on both counts:
I supported an API that had a Batch endpoint that could be “partial success” – and that was a mess.
I have been experimenting with something where you have standardized elements because the Fetch API doesn’t throw on 4XX/5XX, so having one if check, rather than two, makes sense.
Status codes for batch operations is always a mess. Do you return a 400 because one request made no sense even if the rest succeeded, or return a 200? 207 exists but it’s not really directly part of the HTTP spec and only seems to support XML response bodies.
Edit: @lysdexic@programming.dev if the RFC proposed a solution to responses for batch operations where some responses may contain errors, then that would be interesting. The RFC, from what I understand, proposes a format for error responses, but does not seem to support mixed error/success responses.
If both success and error responses include the
successfield, then that can be a common discriminator between bodies of successful responses and bodies of error responses. Where this adds value beyond the request’s status code, I’m not sure. Maybe it’s useful in aggregated responses where partial successes are allowed (likePOSTing a batch of objects)?This does seem a bit heavily worded. There’s likely a reason they originally chose and continue to use that format, and it could be as simple as “all our other APIs use this format” or similar. There’s more to choosing a response schema than what is theoretically the most efficient way of communicating the information.
Thanks, and you are basically correct on both counts:
At this point, it’s an experiment.
Status codes for batch operations is always a mess. Do you return a 400 because one request made no sense even if the rest succeeded, or return a 200? 207 exists but it’s not really directly part of the HTTP spec and only seems to support XML response bodies.
Edit: @lysdexic@programming.dev if the RFC proposed a solution to responses for batch operations where some responses may contain errors, then that would be interesting. The RFC, from what I understand, proposes a format for error responses, but does not seem to support mixed error/success responses.