I'm working on a project where I'm building the frontend and someone else is building an API. I was proposing the following structure for all requests, sent as JSON:
{
"success": true, // true/false
"message": null, // a string if success==false indicating the error
"data": {} // The actual data in the response
}
They are more interested in making the API more RESTful, and instead of a "message" field they are proposing sending a message back in the status code message, in the HTTP headers, such as:
HTTP/1.1 401 Authentication Failed for john.smith@example.com. Please log in again.
and the frontend would display "Authentication Failed for john.smith@example.com. Please log in again." in a popup or something.
I'm worried about length restrictions, but I couldn't find anything indicating no maximum length. Should we ensure we keep those messages to a minimum length? Is there a good reason to not do this, and instead send it back as content (JSON or plain text)?
A little testing will go a long way, but you should be okay to do this and in fact the RFC says specifically:
The reason phrases listed here are only recommendations -- they MAY be replaced by local equivalents without affecting the protocol.
The only possible concern you may have is header size (some servers may have limitations, but I think they are all relatively large) and how some older browsers may react to this. Frankly I think it makes more sense to use the response body since it's easier to interpret and clear, but there shouldn't be anything wrong with your approach.