Error and warning message format in the API response about sample-spring-boot-api-service

[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.