Align with Commonality decision about optional device object and respective documentation

[hdamker]

Problem description

camaraproject/Commonalities#233 has been merged and will be part of Commonalities v0.4.0, therefore we need to adapt the quality-on-demand.yaml accordingly:

Possible evolution

• make device object optional
• add the recommended documentation

Alternative solution

Alternative documentation text if there is a need for QoD API.

Additional context

[jlurien]

A situation that has been raised in other APIs related to allowing an optional device in the input is that our current assumption is that device is always returned as part of responses, within SessionInfo in QoD. This has impact on the implementation as server must decide which identifiers to fill in the response when no device is explicitly indicated.

Even with our current approach of requiring an input device, it is not explicitly indicated if the implementation must reuse the same identifiers that were passed during the session creation or it may return different ones. A problematic case is when the device were identified by some IP address that may have changed. Should the implementation return the identifiers that were used during creation or should it return some other updated or permanent identifier?

[hdamker]

A situation that has been raised in other APIs related to allowing an optional device in the input is that our current assumption is that device is always returned as part of responses, within SessionInfo in QoD. This has impact on the implementation as server must decide which identifiers to fill in the response when no device is explicitly indicated.

Even with our current approach of requiring an input device, it is not explicitly indicated if the implementation must reuse the same identifiers that were passed during the session creation or it may return different ones. A problematic case is when the device were identified by some IP address that may have changed. Should the implementation return the identifiers that were used during creation or should it return some other updated or permanent identifier?

@jlurien Good point ... what is purpose or value of returning the device identifier in the session info (beyond development and testing sessions)?

• If we are returning here another identifier then provided within the request, we are risking to reveal additional personal information, that not a valid option for me
• In case that the device was identified based on the access token, there is also a risk to reveal personal information the actual API client does not need to know

Anyways: we should open a new issue for this, with expectation to document the result of the discussion and potential needed changes. Do you have links within the other APIs?

[jlurien]

A situation that has been raised in other APIs related to allowing an optional device in the input is that our current assumption is that device is always returned as part of responses, within SessionInfo in QoD. This has impact on the implementation as server must decide which identifiers to fill in the response when no device is explicitly indicated.
Even with our current approach of requiring an input device, it is not explicitly indicated if the implementation must reuse the same identifiers that were passed during the session creation or it may return different ones. A problematic case is when the device were identified by some IP address that may have changed. Should the implementation return the identifiers that were used during creation or should it return some other updated or permanent identifier?

@jlurien Good point ... what is purpose or value of returning the device identifier in the session info (beyond development and testing sessions)?

• If we are returning here another identifier then provided within the request, we are risking to reveal additional personal information, that not a valid option for me
• In case that the device was identified based on the access token, there is also a risk to reveal personal information the actual API client does not need to know

Anyways: we should open a new issue for this, with expectation to document the result of the discussion and potential needed changes. Do you have links within the other APIs?

I agree with your comments, in particular withe the problem of revealing unnecessary information to the client in the response, specially in scenarios with aggregator that may not have access to MSISDNs or other sensible information. I don't think there is yet an explicit issue to discuss this. The topic was discussed in the last meeting for DeviceLocation also in relation with making the device optional, and decision was to make an exception for geofencing, because that API returns the device in the response (while verification and retrieval don't).

But as commented here, implications go beyond making it optional, as even if it's required we have to decide whether to keep the same identifiers that were provided (which I guess is the current assumption but has some corner cases). We may need to review in which cases make sense to return the device in the response and which guidelines to adopt.

My worries here is what decision to adopt for the short term (Fall24 meta-release) while discussing the broader implications