Warning and Informational response messages

sections/api-versioning.md

@@ -32,13 +32,13 @@ When new major versions are published the older version must be deprecated follo
 
 ## Minor Version
 
-Minor version numbers are displayed on the API documentation page or part of a special management call to the API URI itself. To support this your API **MUST** implement a response to a GET request to the base URI of the API and return the following metadata in the response:
+Minor version numbers are displayed on the API documentation page or part of a special management call to the API URI itself. To support this your API **SHOULD** implement a response to a GET request to the base URI of the API and return the following metadata in the response:
 
-- **api_name:** The API Name
-- **api_version:** The API Version with major and minor versions
-- **api_released:** The date the API was released
-- **api_documentation:** Links to the API Documentation
-- **api_status:** To indicate whether an API is still active or has been deprecated.
+- **api_name** or **apiName** :  The API Name
+- **api_version** or **apiVersion** : The API Version with major and minor versions
+- **api_released** or **apiReleased** : The date the API was released
+- **api_documentation:** or **apiDocumentation** : Links to the API Documentation
+- **api_status** or **apiStatus** " To indicate whether an API is still active or has been deprecated.
 
 Additional metadata can be added to the response if required.
 

sections/error-handling.md

@@ -66,3 +66,37 @@ A sample 500 Internal Service error:
   }]
 }
 ```
+
+## Warning and Information Responses
+
+It may be appropriate in some scenarios for resource servers to return information about non-critical errors or other significant conditions.
+The necessity of any mechanism intended to convey information about a resource that is not encompassed in the canonical representation of that resource should be carefully considered. When employing extra-data messages, the intent of such messages **MUST** be clearly articulated in API specifications, **MUST NOT** constrain or direct client behaviour (i.e. avoid close coupling) and **MUST NOT** be stateful (i.e. do not represent retention of client state by the server). Warning and information messages **SHOULD** be returned only in exceptional circumstances, **MUST ONLY** be returned by a server and **MUST NOT** be passed to a server by a client.
+
+When utilised. Warning and information messages **MUST** be returned as child objects of a single 'messages' top level collection, and **MAY ONLY** be returned with a success response (Success 200, 201), Bad Request (400) or Unprocessable Entity (422). 
+
+The messages object **MUST** conform to the error object definition described above, and **SHOULD** include an aditional 'severity' attribute.
+
+| Attribute | Description | Mandatory? |
+| --- | --- | --- |
+| `severity` | The severity level of the message. Valid values: 'information' or 'warning'. | Optional |
+
+Sample warning content :
+
+```javascript
+{
+  "data": {
+    "applicationId": "65648987234",
+    "creationDate": "2020-01-01",
+    "applicantId": "123456",
+    "status": "incomplete"
+  }
+  "messages": [
+    {
+      "severity": "warning",
+      "id": "86032cbe-a804-4c3b-86ce-ec3041e3effc",
+      "code": "APP0025",
+      "detail": "application 65648987234 to be retired 2022-01-01 due to inactivity"
+    }
+  ]
+}
+```