Closed trehman-gsma closed 5 months ago
Hi @trehman-gsma +1 on the requirement to clarify this.
my 2cents:
status
as specified in the document MUST be a standard code from a list of Hypertext Transfer Protocol (HTTP) response status codes so this one is NORMATIVEcode
- the guideline is not normative but provide table with value. My understanding is that if a working group or an implementation has to manage this case, they could use this code (eg. if you want throw back an error if Either out of resource quota or reaching rate limiting then it must be TOO_MANY_REQUESTS
code). But, I tend to think that code
in the YAML of a given API are normative. So conformance rules should be something like: an implementation has to provide the code defined in the YAML. Additionally, it is possible to add other code for distinct case not cover in the YAML and in this case it is strongly recommended to use code from the DG tables.message
- Probably we can specify that it is recommended in implementation to use examples provided in the YAML but I do not think we can enforce anything for conformance perspective.@trehman-gsma Thank you for raising this issue. The discussion started in Issue https://github.com/camaraproject/Commonalities/issues/31 but without conclusion.
As RFC 9457 Problem Details for HTTP APIs was published this year we can think of using "Problem JSON" in CAMARA the same way as CloudEvents format was introduced. This RFC is very new so the view of developers (API producers and API consumers) would be helpful.
I would prefer standardized error objects too. But also over multiple APIs. So e.g. there could be one UNKNOWN_PHONENUMBER which could be reused in multiple APIs. So all the fields status/code/message would be the same at all operators, and if possible all APIs, like a global error list.
Using very specific attributes, like in the RFC, I think it's difficult to evaluate. But the idea of global types ("type": "https://example.com/probs/out-of-credit") I would support.
I was working towards some suggestions to #31, which is referenced above, so instead I’ll post it here. While we are still waiting on the EUC feedback/input, I’d here are some suggestions: (Note: I’ve used the QoD API (v0.10.0-rc) as an example API definition for some of these observations and suggestions.)
An example of the modified QoD API (forked from v0.10.0-rc) that is making use of an example CAMARA_common.yaml can be found in the following link: https://github.com/gmuratk/QualityOnDemand-httpresponses/blob/main/code/API_definitions/qod-api.yaml
@gmuratk I think it would be better to continue this discussion about adopting RFC7807/9457 in #31 because there are already important arguments.
Discussed in further issues
Problem description This is related to error responses within the API design guidelines.
An example of a JSON error response structure is below:
I understand that the status values and code values are standardized. Is there guidance on the message value - can it be a custom per Operator?
To elaborate, please consider this example error response from the SimSwap YAML for the scenario where an input phone number cannot be found:
I assume that for this specific scenario, all Operators must align with the same status value (404) and the same code value (SIM_SWAP.UNKNOWN_PHONE_NUMBER). For the message value, can each Operator provide a custom human readable message or must they align with the error message provided in the YAML for the specific scenario?
Possible evolution A paragraph within the Error Responses section of API design guidelines documenting the group view on error messages.