-
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
Which error send back when issue with Device Identifier provided by the API Consumer? #127
Comments
Agree that we need a common behaviour for this. How about 501 with code DEVICE_IDENTIFIER_TYPE_NOT_SUPPORTED instead of DEVICE_IDENTIFIER_TYPE_NOT_MANAGED |
Hello, I was looking at the RFC 9110 definition of 501: "the server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource". In the present case, I think (but I may be wrong in my understanding, please correct me if that's the case) that the server is actually able to handle the request, but not some of the parameters. If the supported parameters are known by the calling party, then I believe it should be a 400 as the calling party is able to change the request input parameters. Technically, a 501 cannot be fixed by the calling party (the code is not available on the server side to handle the request), as per the note inside https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501. To make an analogy, it would be like calling a function inside a program with a parameter that is unknown to the function; this is a caller error, as the function cannot be blamed for not supporting a parameter defined by the caller. What do you think? |
I prefer a 422 status code (Unprocessable content), to indicate that there is an issue with the message content (payload body) provided. Similar handling could apply to other attributes or attribute values in the message content that are optional to be supported. Maybe we even make this error response more generic, as we are working on Commonalities here, such as Attribute Not Supported or Attribute Value Not Supported. 501, as I understand it, is more related to the whole protocol (e.g. method such as PATCH not implemented). |
Good catch, @uwerauschenbach, I am with you for 422. The example in RFC 9110 expresses it this way: "for example, this status code can be sent if an XML request content contains well-formed (i.e., syntactically correct), but semantically erroneous XML instructions." Having a syntactically correct JSON with an inappropriate parameter is a semantic error, so I am in favor of it. |
Thanks for the suggestion. I'm fine with the 422 as well. |
I'm fine with 422 as well |
Hi, this is very relevant topic to enhance our testing guidelines and compliance expectancy. Currently
Should it be a validation order? |
Hi @jlurien
I have asked some colleagues who propose 404 for this specific case, as it is like trying to identify a unique resource with a composite key whose sub-elements point to different resources but intersect to none. It also has the advantage of not telling anything about which property is wrong or right and/or to what it is pointing, as it is the kind of information one might not want to see revealed (a bit like when you enter a bad login/password combination, you don't know which is wrong, just that it failed). What do you think? Best regards, |
@pjhac Now I agree this possibly allows the API consumer to play games by, for example, fixing the IP address and varying the MSISDN to try and find who is using a particular IP address. But they could equally do that with a 404, and really it is up to the API provider to try and stop this type of abuse. And there is anyway no obligation on the API provider to ensure that the identifiers match. More likely, they will accept their "preferred" identifier and ignore the rest. So a positive response does not mean that all provided identifiers agree. Ongoing, I think this problem will anyway go away, as the end user must match that associated with the access token, and only one end user identifier can be used to obtain an access token. |
Hi @eric-murray
My understanding from @jlurien 's post was that the fields, if more than one provided, were all expected to match the same and unique device; in other words, using more than one field should be interpreted as a composite key pointing to a single device. If they are unrelated to each other at provider side, it looks like I may be wrong here.
How will the end-user know which field is preferred, if that is API provider specific / implementation specific? I am wondering what impact it has in terms of user experience, if one has to provide several fields and only one appears to be used in the end. Or is there a way to tell which is preferred? I would expect that reusing the same API calls from provider to provider would give the same results without having to know which parameter(s) provider A needs / wants, then provider B... I may be misunderstanding your point and will welcome additional feedback you can provide. Thanks and best regards, |
Hi, Shouldn't we rethink the device object solution instead? Maybe we should better choose 1-2 options and then support for those becomes mandatory in the server side. Some ideas:
So, wouldn't be enough with phone_number and an alternative to solve M2M scenarios e.g.: IMSI or ICCID? Both mandatory for implementations. |
@pjhac
So, yes, that is the expectation. They should all identify the same end user. But the identifiers are independent and could identify different end users, rather than being a composite key where the end user can only be identified once we have all the pieces. It is an error if the identifiers don't match, and one the API consumer needs to resolve. Likely they made an error in one of the fields, So I think telling the API consumer that the identifiers were valid but contradictory is more useful than just saying there was an error but no give clues as to what it was. Another point is that we cannot mandate that the API provider enforces that all identifiers match the same end user. It may just not be possible for some API providers to evaluate some identifiers.
In one sense, it doesn't matter. The API consumer provides what they know and the API provider processes as they prefer. That could be using one and ignoring the others (so not even validating that the other identifiers identify the same user). It is not practical to mandate that the API provider validates all identifiers passed. For example, determining the end user from a given IP and port (in real-time) is not functionality that all networks support. It is therefore not practical for such networks to support identifying devices by IPv4 address. If the API consumer wishes to know which identifiers a given API provider supports, they would need to read the API provider's documentation. Alternatively, there is a proposal for a mechanism to advertise which parameters are supported. But likely the API consumer is accessing the API via an aggregator, and does not know which network operator will be fulfilling the API call. That is why the API consumer should provide all the parameters they know, as it may be one API provider prefers |
Not all mobile subscriptions will have an associated MSISDN. And a fixed connectivity CPE is also likely not have a phone number. So supporting |
I don't agree with your statement. My point is that implementation of the API must support that if phone_number is included, is processed. I'm not saying having phone_number as required input field in .yaml, I'm saying that if included, there is no option to answer "error I have not implemented support for phone_numbers". Of course if phone_number do not exist (I also indicated example of M2M SIMCards) can't be used by API Clients for that use case. |
This is an interesting one. If API Client sends 2 values not matching the same user and API provider do not support one of the two, request will succeed (failing will be worse?) but API Client will not know which one was used. This reflects that having N options and each API provider supporting different sub-set of them makes scenario more complicated. |
This is the best option with current approach, but I wouldn't say it's a Developer Friendly approach. Should developer ask user for phone_number just in case? Maybe use case does not fit well with asking the user to provide phone_number. Or collect both IPv4 and IPv6 to be 100% sure it will work? |
I agree there are many complexities in device identification!
Even this may be problematic if the use case requires the IP address of the device and the network has no way to determine this from the MSISDN. I agree that there should be a general expectation that
Some APIs include the device identifier in the response, and so can indicate which identifier was used, but this is not the general case. I agree this is a potential issue for other APIs, and can be resolved in the same way, by including the used device identifier in the response if it is required to avoid such ambiguity.
Maybe the aggregator themselves can resolve this. If they know that all southbound implementations support, say, |
Not sure I get your point. You mean use case in an API or the API itself? In which example are you thinking?
Yes, this is an option. In my opinion not a good one in terms of API design as adds yet another complexity to API Consumer. In addition to the collect all and send them its the check responses to find out what was used. Also some APIs may not be designed to have a good fit for this approach. E.g.: QoD has a session concept with the info, there we can say that identifier included is the one used among the ones in the request. But for Location Verification the fit of this info is unnecessary in terms of API design and needs.
For me this seems that we in CAMARA do not create a standard fully-interoperable APIs and then add a requirement to others (aggregators) to solve the issue. There will also exist scenarios where partners directly go to implementations, without an aggregator, in that case we would also need to ask them to either send all, identify whats needed for full coverage or made the If operator 1 / if operator 2. |
An example would be Simple Edge Discovery, where what matters in determining the closest edge site is the allocated device IP address, and not its MSISDN. If CAMARA has a rule that mandates accepting MSISDN as the device identifier if provided, then implementations will be forced to implement MSISDN to IP lookup, which is not trivial. Far better to make it optional, so that those API providers who can implement this do support MSISDN as the device identifier, and those who cannot do not. That way, at least API consumers will get an API that accepts IP address (which may be sufficient for them) rather than nothing at all because an API provider choses not to provide the API rather than implement MSISDN to IP lookup. |
@eric-murray Thank you for your reply addressing my last post. I also think that having optional parameters for the reasons detailed above makes sense; it may look "less constraining", but this can also be an advantage as it gives more freedom while still locking providers to a specific subset of possible fields which, although optional, have well-defined names. (as a side note, an alternative approach is the { "key": "x", "value": "y" } array item structure, which can be repeated as many times as needed inside an array, and virtually accepts any parameter. The problem with this approach is its difficult validation (avoiding repetitions within the array), enforcement of specific key names (unless enumerated are used as only valid key names) and their formats. On less constraining systems where "quantity" of possible combinations matters over "quality" (well-defined, well-scoped field names), this makes sense, but in the present discussion, the low amount of parameters does not really call for such an approach.) Best regards, |
I have a different view about implications of optional parameters |
Ok, I took a look to that API, as I was not very familiar with it. Regarding Simple Edge Discovery, the API states that it is valid for a "network attached device", so IP connectivity is a must. As you said, the IP is what it matters in determination so maybe in this API it's phone_number which has to be removed and make it always work with IP. I'd say that given the clear characteristics of this API, the use of identifiers other than the IP should actually be different API, this API refers specifically to existing connection of the device. |
Thanks for all inputs. Reseting the conversation back to the initial topic and leveraging @jlurien post to have more cases covered. Here a proposal to manage device identifier errors with valuable information send back to the consumer. If the provided device identifier is not compliant
(other example could be added) If a compliant device identifier is provided but the implementation did not manage this identifier type Managed under 422 and following examples should described:
(other example could be added) If the identifier did not match the one got from the 3-legs access token
(other example could be added) If the provided service identifier is compliant but not supported for this service (#145 and #138)
(other example could be added) |
Hi @bigludo7
Following this comment extract from @eric-murray: "A 404 should mean "no valid end user found", rather than "multiple valid end users found and I don't know which one you really meant" -> thinking further about it, I believe that having several fields pointing to more than one device makes the entity "unprocessable" and as such would call for a 422 rather than a 404, I think it makes sense for this particular situation, so I'll follow Eric's comment. Now, I have another question: if none of the provided fields point to a valid / existing device, I believe we would be responding with a 404, is my understanding correct? To summarize, we would have:
I see another case:
These are not blockers for me, I just want to be sure I'm understanding all cases correctly. Best regards, |
@pjhac I was thinking same than you about the case where none of the provided field point to an existent device with 404 but checking QoD API and find that:
So probably we need an agreement for this point. for the other case with the mismatch I would be fine with 422 with message unprocessable entity with multiple inconsistent identifiers. |
Hi, some comments on the latest responses:
|
Hello
New proposal with sorting: Case 0:
(other example could be added) Case 1:
(other example could be added) Case 2:
(other example could be added) Case 3
Case 4
(other example could be added) |
Hello @bigludo7, Thanks a lot for bringing all these together. I think I am fine with cases 0 & 1. For case 4, I would only say "service not supported" and align the remainder of the error message (if any needed) based on Jose's point about disclosure of information. For cases 2 & 3, I am a little torn.
In other words, the end result is still the same for those cases, they are unmanageable. As such, providing an "unmanageable entity" for both should work and not reveal anything about the exact scope of the problem (either unsupported or unable to manage a inconsistency), staying compliant with a response that doesn't reveal too much info. At the end of the day, the user has to provide the appropriate information, in both situations. Best regards, |
Thanks @pjhac
but instead keep it 'vague' like:
I'm not sure to get it because in case of Identifier type not managed we have to be explicit, right? |
Hi @bigludo7, You got it right, that's what I meant. This way we remain consistent with regards to Jose's comment, we don't disclose what happened. I see it (to some extent) the same way we deal with invalid credentials, by not saying which failed / was incorrect. To your question, I think that being more explicit on the field not managed by the implementer does not really bring much value -- it is not supported, so we can't do anything with it (and the caller will have to change their client call implementation anyway). Moreover, the documentation link should be made available such that the end-user knows which fields should be provided. Having to wait for the error "message" to know what can be provided or not is not really friendly in my opinion. It should be made available through the documentation (technically available at all times even outside the scope of an API call -- and, ideally, repeated as a reference in the appropriate error field, like "referenceError"). Now, with that said, the "message" field could be extended to "Unprocessable entity provided, please check the documentation", so at least the caller knows there is something to check to get the appropriate info. I hope this makes sense. Let me know if I'm still not clear or if I missed something important. Best regards, |
Thanks @pjhac As of now the proposal is the following: Case 0:
(other example could be added) Case 1:
(other example could be added) Case 2:
(other example could be added) Case 3
Case 4
(other example could be added) |
Thank you @bigludo7 for putting together the suggested changes, you addressed all my comments. |
Hi, Thanks for the clarification thread. Will align with @jlurien next week. One comment, just to have in mind. For the Case 3 where any of the identitifiers provided do not point to an existing device, would not be
|
Thank @PedroDiez - Yes make sense ! probably better to have |
Hi @bigludo7 - For Case 1, has
For Case 4, as touched upon earlier, Per RFC 9110:
I think a more appropriate code would be 403 Forbidden,
(in Case 4, it is indeed a request forbidden for reasons unrelated to credentials). |
For case 1 I think that error is 400. 401 is to be used in authorization phase, while validating the Authorization header and access token |
Summarizing the discussions in the thread above, I have tried to create a new proposal: Considerations
Summary
Templatesresponse templateA response will group all examples for same operation and status code
example templateOne case will be needed per row in the table above, following this template:
|
just looking for guidance from the group... Which of the above cases, if any, will be applicable for the case where the device schema is compliant, provider supports the parameters submitted, and identifier(s) match a subscribed device, but it just so happens that device is not online, and the requested operation relies on session information. An example use case was encountered in a multi-operator Device Status activity, where the queried device (e.g. for roaming) was not online, and the involved operators had differing opinions on what response to send back. Given this is a thread for Commonalities, so maybe I should expect each API handle their special cases separately, but documenting clearly and stating a normative way so developers get common behavior across different API providers? |
If all the validations that are being discussed here are passed, it is probably a different case not related with device identification.
I think that kind of scenarios have to be treated at Subproject level. In the example above it is not even clear that it has to be considered an error, or it should be covered in a 2xx response with some dedicated property.
I would expect that as well, specially for scenarios closely related to the API logic |
Thanks for all comments & @jlurien for the proposal for case 1 None of the provided device identifiers is supported by the implementation to be sure ... suppose your implem only manage phoneNumber. You get a request with a phoneNumber and an Ipv4 --> no 422 here but we use the phoneNumber without considering the Ip, right? For case 5 I have preference for 422. Indeed we have UC where the /authorize is done for a device to the AS, Authorization performed and then when the API request is done with the token the BE is not able to provide the information for this particular device (token info matches the payload). I will keep 403 when we have token mismatch. |
Yes
I think it is important to agree also on relevant codes, because if we use 422 for different error cases, it would not be easy for developers to distinguish cases otherwise |
Thanks @jlurien for the clarification
Agree. I'm fine with your code proposal in table above to distinguish case. |
Is the above referring to #138? This is a server side error which does not support the method and the client has no way to "correct" it. See 400 vs 500 |
I don't agree with your interpretation. It is actually a semantic error which only the client can "correct" by providing a different phone number. To say it with the words of ChatGPT:
Also your reference 400 vs 500 discourage the use of 501, as it states:
That a phone number can't be supported is anticipated by the server implementation (e.g. landline number for a service which applies only for mobile numbers). The user can correct it by providing another - supported - phone number. BTW: I vote for 422 over 403. |
I think 501 is only appropriate if the functionality will (or can) be implemented at some point in the future. For scenarios where the requested phone number does not and never will make sense (e.g. requesting SIM Swap status for a landline) and so will never be implemented, a 4XX error is more appropriate. My preference is also 422 in this case. |
Problem description
A very small issue but looking for feedback. I guess we can have a common behavior.
In a lot of our API we use the device identifier schema to get the identifier of the line. That's fine, but which error to send back if the device identifier is not supported by the API Implementation? example, an implementation is only able to perform an API with a phone number or IP but not networkAccessIdentifier.
Possible evolution
Agreed to use for this cas error 501 with code DEVICE_IDENTIFIER_TYPE_NOT_MANAGED
Alternative solution
use 500 (with code DEVICE_IDENTIFIER_TYPE_NOT_MANAGED) ?
Let this at the hand of each implem?
Additional context
The text was updated successfully, but these errors were encountered: