Extend the QoD API documentation with details as to what happens when qosStatus changes from available to unavailable

[shilpa-padgaonkar]

Problem description In the documentation, https://github.com/camaraproject/QualityOnDemand/blob/main/documentation/SupportingDocuments/Presentations/QoS%20Status%20and%20Corresponding%20Notification%20Events.pdf, in the flow picture titled "Camara layer logic" it seems like - after the qosStatus changes at step 11 from "Available" to "Unavailable" (not because of duration expiry), we do not terminate the QoS session. This fact is not specified explicitly in the current API documentation clearly. Could we extend the documentation with this point so that it is also clear to the developers. This will then make the developers aware that they need to explicitly invoke a delete session. after getting a notification that qosStatus is unavailable.

Expected action Extend the documentation with the above said missing content.

Additional context

[hdamker]

Results from discussion in QoD call at Dec 15th of this issue:

• Agreed that this issue should be addressed within the documentation, a consistent behavior is across implementations is important
• It's useful that the session resource will exist beyond the time where the qos session became unavailable to allow API consumer who don't use/receive notifications to get the status change and reason (e.g. if polling in regular intervals)
• There will be no case where an "unavailable" QoS session will get "available" again. If we later will define such behavior (that the network tries to reestablish the requested QoS profile) we need to introduce another status (e.g. in context of issue #45, supporting fallback QoS)
• Different options discussed, about how long the session resource should be preserved after the QoS session got unavailable:
  • An explicit delete by the API consumer can not be expected in all cases
  • Binding to requested duration could be difficult to implement
  • Emil proposed to keep the session resource for a fixed time after the session changed to unavailable
    • Time to be defined, should cover at least typical polling intervals
    • Emil will update his presentation with this proposal
• Design target is to allow developers to decide between notifications and polling, both methods should be sufficient to get all important information