Your format looks half baked and not thought all he way through. Take for instance the success bool. What info does this add that error_code and the request's own status code doesn't already send? And what's the point of context if it is both unspecified and optional?
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.
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.
Link seems to be broken for me, but adding your choice of {.html,.pdf,.txt,.xml} to the end of the URL seems to fix it.
I quickly skimmed this, and it looks kinda overwrought to me.
This is the format I’ve been using:
{ success: bool error_code: number, message: “human-centric error message”, context: { optional, user-defined details } }Your format looks half baked and not thought all he way through. Take for instance the
successbool. What info does this add thaterror_codeand the request's own status code doesn't already send? And what's the point ofcontextif it is both unspecified and optional?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.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.