-
Notifications
You must be signed in to change notification settings - Fork 28
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Adopt RFC 9457 error response format #133
Comments
My preference is to go for the RFC error format. It might be a painful change now but we have a solid foundation for the future that also allows standard compliant extension by machine-readable fields. |
Hello, I would have been tempted to support RFC format, but the disadvantages listed by @eric-murray above somehow discouraged me. In particular, the "status", as defined in the RFC, has to be redundant of the HTTP Status Code, but I know by experience that poorly designed/implemented clients and servers are going to misuse it (a recurring situation was to provide a sub-API response in such "status" parameters). If the server violates RFC9457, the client cannot really know it, and as such should stick to the HTTP Status Code, which makes this additional "status" meaningless. I'd personally find more useful to have an error "code" (like DEVICE_IDENTIFIER_TYPE_NOT_MANAGED as proposed in #127 that can be enumerated/listed in the API) and a "reason" (RFC9457 "title" equivalent) describing the original issue. Any other parameter should be optional, in the sense that "code" and "reason" should be enough to identify the issue. The parameters names can be changed to whatever makes sense, but they should be minimal and required, while providing sufficient information. As for extensions, they are implementation-dependent and/or API-dependent and/or problem-dependent, so defining them might prove to be a daunting task, especially if we want to have a well-defined listing of potential problems. |
Thanks @eric-murray for creating the consolidated issue out of the older discussions in #31. As requested by @bigludo7 in this discussion comment, #125 (comment) , we kindly request all commonalities participants and other interested Camara members to provide a "formal" position on this issue. |
Dear colleagues,
According to RFC9457, “status” is optional. So it can be omitted (and we could clearly state that there is no need to include it).
There’s typically no loss of information in such case, as the status code is anyway contained in the HTTP response.
The only use I see for “status” in the message content is when persisting the error response (which will not persist protocol information such as the status line).
Indeed many errors are implementation-dependent, so often people shy away from defining them. Some APIs may nevertheless wish to define standard error situations.
For those, it may make sense to define a framework, based on the RFC 9457 extension rules.
Kind regards,
Uwe
From: Pierre Close ***@***.***>
Sent: Monday, February 5, 2024 5:42 PM
To: camaraproject/Commonalities ***@***.***>
Cc: Uwe Rauschenbach (Nokia) ***@***.***>; Comment ***@***.***>
Subject: Re: [camaraproject/Commonalities] Adopt RFC 9457 error response format (Issue #133)
Hello,
I would have been tempted to support RFC format, but the disadvantages listed by @eric-murray<https://github.com/eric-murray> above somehow discouraged me. In particular, the "status", as defined in the RFC, has to be redundant of the HTTP Status Code, but I know by experience that poorly designed/implemented clients and servers are going to misuse it (a recurring situation was to provide a sub-API response in such "status" parameters). If the server violates RFC9457, the client cannot really know it, and as such should stick to the HTTP Status Code, which makes this additional "status" meaningless.
I'd personally find more useful to have an error "code" (like DEVICE_IDENTIFIER_TYPE_NOT_MANAGED as proposed in #127<#127> that can be enumerated/listed in the API) and a "reason" (RFC9457 "title" equivalent) describing the original issue. Any other parameter should be optional, in the sense that "code" and "reason" should be enough to identify the issue. The parameters names can be changed to whatever makes sense, but they should be minimal and required, while providing sufficient information.
As for extensions, they are implementation-dependent and/or API-dependent and/or problem-dependent, so defining them might prove to be a daunting task, especially if we want to have a well-defined listing of potential problems.
—
Reply to this email directly, view it on GitHub<#133 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AAKRTHPQL4AK5A75UQTYIT3YSEDW5AVCNFSM6AAAAABC2HTCRKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMRXGQZDKNBXGY>.
You are receiving this because you commented.Message ID: ***@***.******@***.***>>
|
Vodafone's preference is to adopt an RFC 9457 compliant error response. The only mandatory requirements on API providers to support this change would be:
Nothing else is required. Including a Discussions on future use of the |
Hi @eric-murray
I understand your point, but I was feeling that having an idea of the possible values (or their format, at a minimum) could have helped map the actual parameters to the RFC 9457 ones. In particular, "title" rather seems like a short sentence (and not a "code" type of value), which was why I was mentioning it as a "reason". Now, with that said, I do not see another parameter in the RFC that could fit such "code" as defined at present time, so if only the two parameters you indicated would be mandatory requirements, we can converge to something common. I am then fine to go for a RFC 9457 compliant error response, and possible format and values to use for "title" and "detail" can be discussed separately. Best regards, |
T-Mobile US preference is to adopt RFC 9457 compliant error response. |
We understood the value to move to a standard but from our perspective as the RFC 9457 is not widely used in the industry we did not see enough value to change all CAMARA assets. As such Orange preference is to not move to RFC9457. |
The position from Telefónica is also to keep the current agreement and not move to RFC 9457. The current format is in line with the format used by big players and familiar to the developers, while the RFC is not widely adopted. The impact of a this change as this moment is huge, as there are many integrations going on. Moreover, the advantage of the proposal is to adhere to a standard but at the same time it changes key aspects of the standard. |
@eric-murray Could you explain why do you think that the RFC9457 says
My reading of the above is that RFC9457 can't be used without using the BTW: on the mailing list of RFC9457 there are several concerns about using the Note: this isn't yet a position of DT, just a personal comment/question from my side. |
Speaking as myself (not my company) wrt the comments of not being widely adopted by industry - the RFC is an update to one that was not widely adopted (likely a driver for the update). Given the update was published 7 months ago, I would not expect it to be widely adopted. I would also not enjoy a precedent that industry adoption has to occur within 7 months of publication for any specification as most would not pass that test. wrt the proposal, I feel that is clear. Other comments appear to be:
Regardless, the RFC only recommends link de-referencing when debugging, effectively making it a no more than an unique identifier / tag. In either case, the IANA registration is optional as it is "for common, widely used problem type URIs, to promote reuse." <- that implies to the Internet as a whole. I would argue that CAMARA types would not immediately qualify at that level. Initially I was in agreement with posts above but not now I feel it can be done as the RFC says and work for both secanrios. I am just uncomfortable with it but I note we often use types like with similar information elements of a URI. The additional obligation on our part is to provide some pages that it can resolve to by default if CAMARA provides the URI. Finally on this issue, I agree with the observation that 'type' does not have to be sent on production servers. They usually represent certified client and server code so there is no point in sending it unless programmatic disambiguation is required.
|
Hi @hdamker
As noted, the I also agree there is generally no value to the And I also agree that using |
I think that the key to enhance the current errors is to analyse why test users do not understand why they are getting a particular error message, I don't think that renaming the keys from code/message to title/detail would solve the problem, as long as we keep the same values. We probably have to define more explicit codes for expected problems and document better examples in the specs. |
@jlurien Of course, RFC 9457 has somewhat changed the intended use of the Better documentation is always preferable, but it is a universal truth that developers are not great fans of reading documentation. Requests for support generally come from developers who did not read through the documentation. |
Hi @eric-murray Thanks for the clarification that your main motivation for your original issue #31 and your support here for RFC 7807 and now RFC 9457 was to introduce an external documentation link. My view is that this can't be achieve with the There is a requirement within the RFCs that the URI value in Here are two examples of organisations which have adopted RFC 7807/9457, but explicitly decided against resolvable URI in the
Here is one example which has adopted RFC 9457 and at least defined how to build resolvable URLs for new problem types:
My main point is that the following parts of your proposal (from "Further edit") would not comply with RFC 9457:
The RFC says for this predefined problem type: "When "about:blank" is used, the title SHOULD be the same as the recommended HTTP status phrase for that code", it MAY be localized. But that's in contradiction to your proposal "Rename the code field to title, with no other change to how that field is currently used". We are currently using the field also with API specific strings.
That would be completely in contradiction to the definition in RFC 7807 and RFC 9457, as explained above. So my personal position is that adapting the RFC 9457 partially without following the intention of the RFC and using "problem types" as defined is worse than staying with our current proprietary structure. The only advantage would be that we then in same club as 3GPP, but still without a usable documentation reference. To address of your initial idea of having a link to documentation we could add a proprietary optional parameter to our proprietary CAMARA error format, like the |
I think it is important to note from RFC 9457 also “using relative URIs can cause confusion, and they might not be handled correctly by all implementations.” – the RFC discourages use of relative URIs and “The type URI is allowed to be a non-resolvable URI … However, resolvable type URIs are encouraged by this specification because it might become desirable to resolve the URI in the future.” Other solutions noted above discuss the challenges of this dual use and solved them, e.g., use of an accompanying href for developer documentation. Based upon the RFC guidance and other solutions, I would propose adopting RFC 9457 with the following constraints: A. The type property is restricted to URNs as defined in RFC 8141 from a managed URN namespace managed by CAMARA. These URNs are not relative nor are they intended to resolve to locators. B. Developer targeted information generally describing the error or related documentation will be a URL contained in a href property in the error. Per RFC 8141, URNs are assigned under a URN namespace with “intent that the URN will be a persistent, location-independent resource identifier. A URN namespace is a collection of such URNs, each of which is (1) unique, (2) assigned in a consistent and managed way, and (3) assigned according to a common definition.” Item A avoids the pitfalls we have identified while B supports the of the type property being a locator as described in RFC 9457. As for the URN namespace, we would be to set up the namespace (NSS). The format would be urn:camara: The type value then is interpreted as follows:
|
Following slides were added to Meeting Minutes in Wiki to be reviewed during the March 4, 2024 call. |
Now this is an interesting but separate issue, and one I did want to raise at some point. The current valid values for the But, as you point out, some APIs are introducing their own
Can you clarify why you think the
As my intended use case is non-prod API testing, I'd be happy if we mandate strict RFC 9457 compliance for the I also agree that my intended use case can be supported by a proprietary error response. Proprietary formats can support almost anything. |
Problem description
The current CAMARA error response has some drawbacks:
code
values are too narrow to provide much more detail than the HTTPstatus
value itselfPossible evolution
Adopt the RFC 9457 error format as follows:
code
field totitle
andmessage
field todetail
type
field which can be used to link to better documentation, for example:Additional context
This issue was already raised in Issue #31, which proposed adopting the now obsolete RFC 7807. There was a long conversation in that issue, which is summarised below.
(EDIT - To be clear, the "advantages" and "disadvantages" listed below are summarised from the conversation of Issue #31. They are not my personal nor Vodafone's opinion. This can be found in my comment below.)
Advantages of adopting the RFC error format
cause
, to be adopted whilst remaining standard compliantDisadvantages of adopting the RFC error format
type
cannot be automated using code generators, which complicates the construction of error responses (for those that want to include thetype
field) and hence makes more work for API implementorscode
values than are currently defined, and standardising their use across APIscode
andmessage
, though the CAMARA format follows none of them exactlyFurther edit
It was commented at the recent TSC meeting that the proposal was not clear, so I will clarify that now:
code
field totitle
, with no other change to how that field is currently usedmessage
field todetail
, with no other change to how that field is currently usedstatus
fieldtype
field as follows:about:blank
Content-Type
should be changed toapplication/problem+json
, but that is not widely used and I always take a pragmatic approach to these things.And that is it. None of this rules out further evolution of the error response in future, possibly towards a "purer" implementation of RFC 9457 if that would be useful. But nor does it require it.
The text was updated successfully, but these errors were encountered: