clean up error and success messages to be consistent

[mwhite]

Relatedly, I think it might be a good idea to make JSON error information in the response an optional rather than required part of the API.

[mwhite]

For a few reasons:

• We don't want to encourage client implementations to expect JSON error info to be there and then fail to work with a provider implementation that was lazy and didn't include that part.
• We don't want to make providers return error messages that aren't exactly what they mean. Let them return an error message if they want, and it will be a useful error message. If we force them to return an error message then it will just be noise. If we want to force providers to provide more detailed error information than an HTTP status code, then we could just explicitly define the meaning of all status codes for all requests.

[bobjolliffe]

+1

On 21 February 2013 17:53, Mike White notifications@github.com wrote:

Relatedly, I think it might be a good idea to make JSON error information in the response an optional rather than required part of the API.

— Reply to this email directly or view it on GitHubhttps://github.com/facilityregistry/fred-api/issues/40#issuecomment-13902864.

[mberg]

That's fine. Should I remove from API specs or just say it's OPTIONAL?

On Mon, Feb 25, 2013 at 1:29 PM, bobjolliffe notifications@github.comwrote:

+1

On 21 February 2013 17:53, Mike White notifications@github.com wrote:

Relatedly, I think it might be a good idea to make JSON error information in the response an optional rather than required part of the API.

— Reply to this email directly or view it on GitHub< https://github.com/facilityregistry/fred-api/issues/40#issuecomment-13902864>.

— Reply to this email directly or view it on GitHubhttps://github.com/facilityregistry/fred-api/issues/40#issuecomment-14034549.

[ghost]

I would advise that there be some mechanism of returning application layer error codes. IMO, since HTTP is a transport, HTTP errors should be kept for transport level errors or application server issues (couldn't process message, couldn't find resource, service unavailable, etc...).

There are some cases where you want to return other error codes that are related to business constraints or application level errors. For example I may have a business constraint in my jurisdiction that facilities MUST carry information about the number of beds via an extended property, or that equipment codes are LOINC, or phone numbers be in a particular format, etc.. In these cases, it is not suitable to just return an error code as it would be quite generic.

I would keep error codes mandatory from a semantic perspective (they don't have to be present in the message, but all conformant clients must be able to interpret and/or do something with them). Even if the requirement is that clients simply display the error message on the user's screen or log it to a file.

[mwhite]

That seems reasonable. Is it typical to have the application layer error codes be the same as or different from the HTTP status codes?

[edjez]

Ready to close- http://facilityregistry.org/?#http-response-codes docs should say "The body includes an object describing both the code and OPTIONALLY the message"

[mberg]

Updated