Align quality-on-demand with Commonalties regarding optional device object and error messages

[hdamker]

What type of PR is this?

Add one of the following kinds:

• correction
• documentation

What this PR does / why we need it (Updated):

• Add documentation about "Handling of device information" within the API description. Made device parameter optional within createSession
• Aligned Device object and info object with Commonalities
• Updated errorMessages according to Commonalities.
  • Added 422, removed 501 (as createSession is not optional within the API, and then 501 is not any more used)
  • Replaced 400 error response examples with Generic400 from Commonalities, introduced specific error code QUALITY_ON_DEMAND.DURATION_OUT_OF_RANGE

Which issue(s) this PR fixes:

Fixes #313
Fixes #315
Fixes #316

Special notes for reviewers:

Intentionally only done for quality-on-demand to reduce potential merge conflicts.
Done for both APIs quality-on-demand and qos-profiles.

Changelog input (Updated)

Made device object optional within quality-on-demand, added documentation according to Commonalities
Updated error messages according to Commonalities, especially error messages related to device object
Introduced specific error code QUALITY_ON_DEMAND.DURATION_OUT_OF_RANGE

[hdamker]

@maxl2287 @akoshunyadi @jlurien I created the PR by intention first as draft, but would be great if you can already review.
I would like to rebase if #325 is merged (which is also correcting some errorMessages).

@eric-murray the documentation I copied from Commonalities is only referring to "device" associated with the access token. I get your point that "end user" is more correct. But do you have a proposal not to confuse API consumers here? My proposal to put "(and device)" behind end user is most probably not the best ...

[jlurien]

@hdamker are you planning to remove the draft status? This PR is key for the meta-release as it incorporates the alignments to guidelines. Once this is merged, we can adapt the remaining ones (listSessions, Provisioning) to the updated content. For listSessions I have to define same behaviour for device optionality and adopt the new errors.

[hdamker]

@jlurien Yes, removed the draft status now to be able to discuss it within the meeting. We should agree who (which PR) is changing the 404 errors.

[hdamker]

@camaraproject/quality-on-demand_maintainers:We are most probably also impacted by the discussion in camaraproject/Commonalities#259 about potential misuse of the API behaviour. Let's discuss how to deal with it in the meeting.

[hdamker]

As discussed within QoD Call:

• Incorporate the Generic404 definition
• Add UNIDENTIFIABLE_DEVICE for 422
• Differentiate SessionInfo for request and response (for Device in response object need to be omitted or clearer defined #328) and add proposal from Device in response object need to be omitted or clearer defined #328
• Add clarification to all endpoints:
  The session must must have been created by the same API client given in the access token
• Apply respective changes to qos-sessions

[jlurien]

Some other fixes:

• externalDocs:
  description: Product documentation at Camara
  url: https://github.com/camaraproject/

should be

externalDocs:
description: Project documentation at CAMARA
url: https://github.com/camaraproject/QualityOnDemand

• createSession should have 404 error

[hdamker]

externalDocs:
description: Project documentation at CAMARA
url: https://github.com/camaraproject/QualityOnDemand

ExternalDocs object updated in both APIs (I had planned it for the release PR).

• createSession should have 404 error

Ah, yes - due to the new DEVICE_NOT_FOUND - Thanks! (Nevertheless a bit strange to return 404, if the requested resource has not even been created).

[jlurien]

Another ones:

• org.camaraproject.qod.v0.qos-status-changed -> org.camaraproject.quality-on-demand.vwip.qos-status-changed

Long but it should be the new API name, if we finally keep the proposal.
vwip should be changed to v0 for the rc PR but as we know it will be v0 it doesn't have an impact

• DurationOutOfRangeForQoSProfile should not be part of Generic400 as that one should only contain the common ones. A separare 400 response would be needed for the operations that receive a duration

• In New API QOD Provisioning #299 I have considered a Generic404 with just NOT_FOUND and GenericDevice404 with both NOT_FOUND and DEVICE_NOT_FOUND, and I have applied the latest only to operations that may expect a device (and also 422 applies to them)

[hdamker]

• org.camaraproject.qod.v0.qos-status-changed -> org.camaraproject.quality-on-demand.vwip.qos-status-changed

That outside of the scope of this PR, at least we should open an issue for that to make the change more transparent.
Is there a guideline regarding the versioning of events which is different from the API versioning? Otherwise it would be in the release v0.11rc1, but I'm not sure if this is correct.

[hdamker]

• DurationOutOfRangeForQoSProfile should not be part of Generic400 as that one should only contain the common ones. A separare 400 response would be needed for the operations that receive a duration
• In New API QOD Provisioning #299 I have considered a Generic404 with just NOT_FOUND and GenericDevice404 with both NOT_FOUND and DEVICE_NOT_FOUND, and I have applied the latest only to operations that may expect a device (and also 422 applies to them)

I agree that it is clearer if it is visible which examples are belonging to which operation. But in https://github.com/camaraproject/Commonalities/blob/a4f409d3c9e278bd30afc838cee8a261ff450939/artifacts/CAMARA_common.yaml#L209 Generic404 is defined with both NOT_FOUND and DEVICE_NOT_FOUND and even a placeholder for specific codes. But ok, I will apply the approach from your #299.

[jlurien]

• org.camaraproject.qod.v0.qos-status-changed -> org.camaraproject.quality-on-demand.vwip.qos-status-changed

That outside of the scope of this PR, at least we should open an issue for that to make the change more transparent. Is there a guideline regarding the versioning of events which is different from the API versioning? Otherwise it would be in the release v0.11rc1, but I'm not sure if this is correct.

Good question. I though it was intended to match the major version of the API, but I guess the major version of the API could change without evolving the event version (but not the opposite).

[hdamker]

• org.camaraproject.qod.v0.qos-status-changed -> org.camaraproject.quality-on-demand.vwip.qos-status-changed

That outside of the scope of this PR, at least we should open an issue for that to make the change more transparent. Is there a guideline regarding the versioning of events which is different from the API versioning? Otherwise it would be in the release v0.11rc1, but I'm not sure if this is correct.

Good question. I though it was intended to match the major version of the API, but I guess the major version of the API could change without evolving the event version (but not the opposite).

Created #332 for the larger topic that we missed the changes within the Event subscription model, which impacts also our implicit subscriptions. Changing the event name is the smaller problem here (btw: I would stay here with v0, not using "wip" in between - the risk is too high to oversee this in the release PR. The version of the event will get only "visible", when there is a released API Version).

[hdamker]

• DurationOutOfRangeForQoSProfile should not be part of Generic400 as that one should only contain the common ones. A separare 400 response would be needed for the operations that receive a duration
• In New API QOD Provisioning #299 I have considered a Generic404 with just NOT_FOUND and GenericDevice404 with both NOT_FOUND and DEVICE_NOT_FOUND, and I have applied the latest only to operations that may expect a device (and also 422 applies to them)

I agree that it is clearer if it is visible which examples are belonging to which operation. But in https://github.com/camaraproject/Commonalities/blob/a4f409d3c9e278bd30afc838cee8a261ff450939/artifacts/CAMARA_common.yaml#L209 Generic404 is defined with both NOT_FOUND and DEVICE_NOT_FOUND and even a placeholder for specific codes. But ok, I will apply the approach from your #299.

@jlurien Done in 55c609a. Please check.

[hdamker]

@jlurien @maxl2287 @eric-murray @RandyLevensalor The PR should be ready to be merged. Would be also good to get it merged soon, so that we can base the other PRs on it. Can you do a timely final review?

[jlurien]

LGTM, I assume #335 as a separate one but it is quite independent so merging order should not be relevant

[RandyLevensalor]

LGTM

[hdamker]

Given the two approvals from @RandyLevensalor and @jlurien (before the last trivial change) I will merge this one now, so that we can continue to align the other open PRs (if needed).

Please open issues if there other alignment points with Commonalities are open.