Problem description
CAMARA error responses are necessarily brief, and can only give limited information on what caused the error. It can be difficult for a developer to understand why their request was not accepted by the service API based on the error response alone. Good documentation is useful, of course, but this would need to be extensive to identify all request format requirements, making it difficult for a developer to find the relevant section dealing with their particular problem.
Possible evolution
Some error response formats allow for a resolvable documentation link (URL) to be included in the error response. This can have various names, some of which a developer may already intuitively understand, such as "type" / "@type", "href" or "referenceError".
This issue does not propose a specific name. That can be discussed within the comments, and depends upon how closely CAMARA wishes to conform to existing standards and conventions.
It would not be expected that such documentation links would be provided in production systems. This proposal is to make it easier for developers to learn how to access CAMARA APIs, not to automate error handling.
Alternative solution
None proposed
Additional context
This issues replaces issue #133, which is now closed. A separate issue will be raised as to whether the CAMARA error response schema should conform to RFC 9457.
Problem description CAMARA error responses are necessarily brief, and can only give limited information on what caused the error. It can be difficult for a developer to understand why their request was not accepted by the service API based on the error response alone. Good documentation is useful, of course, but this would need to be extensive to identify all request format requirements, making it difficult for a developer to find the relevant section dealing with their particular problem.
Possible evolution Some error response formats allow for a resolvable documentation link (URL) to be included in the error response. This can have various names, some of which a developer may already intuitively understand, such as "type" / "@type", "href" or "referenceError".
This issue does not propose a specific name. That can be discussed within the comments, and depends upon how closely CAMARA wishes to conform to existing standards and conventions.
It would not be expected that such documentation links would be provided in production systems. This proposal is to make it easier for developers to learn how to access CAMARA APIs, not to automate error handling.
Alternative solution None proposed
Additional context This issues replaces issue #133, which is now closed. A separate issue will be raised as to whether the CAMARA error response schema should conform to RFC 9457.