In the above responses, I am sending a "result" key that holds a boolean value (true / false). True in case of success and false in case an error occurs.
The second key is "message" that holds the respective messages.
The reason I am asking this question is because one of my friend claims that its not a standard way of sending API responses and that we do not need to send the "result" key at all. We should return a key "errMsg" with the error message in case of error and in case of success we can send a true value. And users who are using the API can check if the "errMsg" key exists then handle the response as an error otherwise assume it as a success.
So can someone throw some light on this please?
Thanks in advance
05-02-2013, 02:20 PM
I would suggest looking at some outputs of common public API's. For example Ebay, Amazon, Paypal and such should provide enough info on how the standard output should look like. It would be wise to ask yourself, what do I gain/loose with having result key-value pair? Does it offer better user/developer experience when using your API or does it not? In my opinion, enumeration value like your result makes sense for indicating output status.
05-02-2013, 03:55 PM
I personally doubt there's much of a "standard" in this regard: for something that simple, I think any developer half-ways deserving of the name can understand your posted system and figure out how to work with it -- which seems good enough to me, regardless of whether it's the absolute "best" way or not. :)
FWIW, the "standard" on the project I'm on here at work is similar: most JSON responses have a 'result_code' and 'result_msg' field at the top level, and then additional parameters as applicable, often in arrays, sometimes 2 or 3 levels deep. Fake example:
"bar": "another thing"
"comment": "This is only a test."
"comment": "This is only another test."
05-02-2013, 05:06 PM
As far as I've gathered from my short experience of working with APIs, you pretty much set your own standard. As long as you keep everything consistent and do return some form of success/error response it's entirely up to you.