Error and warning message format in the API response

[plavjanik]

• Migrate the documentation about message format to the documentation of the sample service
• Provide practical instructions and examples of how to use it in the following scenarios:
  • Response for the REST API with errors and warnings
  • How to add a new message
  • How to throw exceptions in the code and how to convert them to REST API responses (PetControllerExceptionHandler.java which provides a recommended style)
  • Provide links to good tutorials about error handling in Spring and Java
  • An internal message is written to the server log
    • Improve the generating of the message instance ID (directly in the ApiMessage class)

[plavjanik]

Original documentation (taken from https://docops.ca.com/x/r9SVH):

REST API Document Format

Document format

The response is to be in a JSON format and media type value is application/json. The name of the fields is to use camelCase. If the request is processed without any errors and warnings, then the response format is to be either a JSON object or JSON array. If the request is processed with an error or warning, then the response is to follow the JSON format as in the following code:

{
  "messages": [
    {
      "messageType": "ERROR",
      "messageNumber": "CSR0001",
      "messageContent": "Pet with id '404' is not found"
    }
  ]
}

The above response contains a messages section. The messages array is a place for application (or service) status and message descriptions to complement and enhance the basic HTTP status codes that are returned in the HTTP status line.

Rules for messages

Follow the principle that message key (for example org.zowe.sdk.apiml.serviceCertificateNotTrusted) is for the code and message content (readable text) is for people. When an error occurs, The HTTP status codes are returned. Provide more details within this message structure. The meaning of the fields is (in order of importance):

• Required:
  • messageType - severity - ERROR, WARNING, INFO, DEBUG, or TRACE
  • messageNumber - typical mainframe message ID (not including the severity code) that can be found in CA documentation
  • messageContent - Readable message in US English
• Optional:
  • messageReason - Supplements the messageContent field, supplying more information about why the message is present.
  • messageAction - Recommendation of the actions to take in response to the message.
  • messageKey - unique message key - describing the reason for the error. It should be a dot-delimited string tld.provider.service[.subservice].detail. For example: org.zowe.sdk.apiml.serviceCertificateNotTrusted. The purpose of this field is to enable UI to show a meaningful and localized error message. The message key is used instead of the message number as the number makes the code hard to read, and makes renumbering difficult and error-prone.
  • messageParameters - error message parameters. Used for formatting of localized messages.
  • messageInstanceId - unique ID of the message instance. Useful for locating of the message in the logs. The same ID should be printed in the log.
  • messageComponent - for support and developers - component that generated the error (can be fully qualified Java package or class name)
  • messageSource - for support and developers - source service that generated the error (can Open Mainframe service name or host:port).Be sure to include as much useful data as possible and keep in mind different users of the message structure. However, be mindful not to leak data that should be kept private or implementation details to avoid breaches in security.