Warning and Informational response messages #77
Conversation
Update to api-versioning.md to provide both camelCase and snake_case version payload to align with updated definitions.md case consistency reqirement. Change MUST to SHOULD - this is a significant requirement will not be implementable in some cases.
Add messages top level member and warning and information messages
|
Hi, |
sections/error-handling.md
Outdated
| ## 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. | ||
| When employing extra-data messages, the intent of such messages **MUST** be clearly articulated in API specifications, **MUSTNOT** unduely 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. |
There was a problem hiding this comment.
I'm not really sure that we can really control what a client does, but it seems kind of moot. If it's about passing warnings from a client to a server as a part of an API, again, I'm not sure what this achieves. If an API needs such a design, why would it be excluded? A common format for warnings makes sense in general though.
Addresses Issue #61
Optional 'messages' top level member for non-critical errors and other significant transactional information.
The messages header provides flexibility, though introduces potential issues, including the difficulty of clearly describing intent within an API specification without relying on implied knowledge or back-channel communication. 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.