I am developing a web application and struggling to follow a clear semantic while returning response to the client. Taking an example of authenticating an user there can be following scenarios:
1. Request is successful
The user is authenticated and I send a JSON response
{success: true} // and an optional message field?
2. An application error occurred
User is not authenticated.
{error: true, message: 'Invalid email or password'} // Again I am not sure if I should let client decide to show the error message
3. System error
Bad SQL query, DB crashed etc. typically server should return 500 status code but should I again send the JSON response with it? if yes, how much should I tell the client? because the client or user may not be interested in knowing that DB crashed or SQL was not well formatted.
Any other suggestion/modification is most welcome.
Best Answer
If in doubt, D.R.Y.
As a client to a REST service, an empty 204 response is quite enough to indicate that everything worked and that the client doesn't need to do anything else.
A client will usually expect authentication/authorisation errors to be handled with a 401 response. No additional information is needed; in fact, the less information you provide is less information available to a potential intruder who is trying to guess different potential username and password combinations.
Other types of errors, such as a badly formatted query string, errors in the HTTP request body, or validation failures would typically return 400 Bad Request.
In the case of 400 Bad Request, it is certainly worth returning a response with detailed information which describes exactly how the request might be wrong - whether it's an issue with the structure of the data, the data format, a missing field, a validation error, some unexpected information, etc.
As a client to a REST service the quality of the message and detail provided in a 400 error response can be the difference between hours/days of frustrating trial-and-error debugging versus a quick 5-minute bugfix.
A simple 500 Internal Server Error response is all you need here. A client cannot do anything about a bug in the server code, nor the fact that the database crashed or the server failed in some unexpected way. When a client receives '500' the only sensible thing for that client to do is simply to give up (and maybe try again much later..)
Information about server-side errors are important to whoever looks after the server, so the best place for that information is your server-side logs.
Time spent trying to send information back to a client would be much better served by ensuring the logs contain detailed information which allow somebody to debug the server.
In general
Don't return your own hand-rolled JSON error status flags from a REST API for scenarios which are already handled by well-known HTTP status codes. HTTP client libraries are generally already capable of handling those return codes, so not only are you potentially reinventing the wheel on the server and making your API unnecessarily complex with extra objects and fields, you're probably also forcing the client to do the same, and making unnecessary extra work on the client side too.