Update wording in the qod-provisioning API

[jlurien]

What type of PR is this?

• documentation

What this PR does / why we need it:

Being "provisioning" a process and not a "resource", it does not sound well to create or delete a provisioning, but to trigger the process or to revert or revoke the assignments done by a previous provisioning process.

Which issue(s) this PR fixes:

Adresses part of #415 but will not close it

Special notes for reviewers:

Only some descriptions and operationIds have been adjusted for this Meta, as there is no a clear alternative for the names of the resources used in path, scopes, etc, and this change is critical to be done for this Meta-release without a thoughtful discussion.

As this is still an initial version of the API we will work further on those aspects towards a future meta-release, taking feedback from early integrations.

Changelog input

- operationIds renamed and some descriptions changed

Additional documentation

This section can be blank.

docs

[RandyLevensalor]

Update feature files to match new operationIds.

Use a single term to replace delete. I suggest using revoke and not using revert.

[eric-murray]

Changing the operationId will require an update to associated the feature file

[tanjadegroot]

Some further suggestions and it is OK for me. thanks !

[tanjadegroot]

check the consistent use of

• "QoS profile" consistently (with "profile" with lower case "p")
• assignment --> association

line 16 remove: "(user equipment)"

[jlurien]

• Profile -> profile
• UE removed

[hdamker]

Note: I replaced my complete previous comment. The reason is that I hadn't realized that the API has actually a resource noun (device-qos) which makes sense if understood as a short for "device-qos-assignment" or "device-qos-association" or even "device-qos-provision" (the result of a provisioning). The challenge is that this short form has no plural form.

Beyond that the problems to address are more the Schemata names (which can be replaced without impact on API clients), the parameter provisioningId (which can't be changed without a breaking change), and beyond that mostly the descriptions and operationIds which are not referring to the resource which get created, read and deleted. I agree that this shouldn't be done short-term.

The operationIds need to be changed again later, as they should follow the chosen resource name.

In summary I'm fine with the PR, but would propose to add some disclaimer, that it is an initial version and a later version will rename certain operationIds, schemata names and also property names to make it more consistent regarding the actual resources.

BTW: If the API name should be qos-provisioning or qod-provisioning is also worth a discussion. A QoS profile will be provisioned, but not a "QoD" (which is the name of another API which is about has sessions as resource) ... the title of this PR is using "qos-provisioning API" ;-)

[tanjadegroot]

Note: I replaced my complete previous comment. The reason is that I hadn't realized that the API has actually a resource noun (device-qos) which makes sense if understood as a short for "device-qos-assignment" or "device-qos-association" or even "device-qos-provision" (the result of a provisioning). The challenge is that this short form has no plural form.

"device-qos-association" would be the right resource name for this API IMHO. It took me also a while to understand that that is the actual resource being managed through this API.

Beyond that the problems to address are more the Schemata names (which can be replaced without impact on API clients), the parameter provisioningId (which can't be changed without a breaking change), and beyond that mostly the descriptions and operationIds which are not referring to the resource which get created, read and deleted. I agree that this shouldn't be done short-term.

The operationIds need to be changed again later, as they should follow the chosen resource name.

In summary I'm fine with the PR, but would propose to add some disclaimer, that it is an initial version and a later version will rename certain operationIds, schemata names and also property names to make it more consistent regarding the actual resources.

I would also plan to renaming of the resource to "device-qos-association" as well, as anyway you are doing breaking changes. it will much clarify the usage of the API.

BTW: If the API name should be qos-provisioning or qod-provisioning is also worth a discussion. A QoS profile will be provisioned, but not a "QoD" (which is the name of another API which is about has sessions as resource) ... the title of this PR is using "qos-provisioning API" ;-)

I agree the usage of "qod" is confusing and should be "qos"

[hdamker]

Changing the operationId will require an update to associated the feature file

@jlurien could you address that within the next two days, so that we get ready for Feb 28th?

[jlurien]

Changing the operationId will require an update to associated the feature file

Updated test plan aligned with the new operationIds and some typos fixed as well

[jlurien]

Some further suggestions and it is OK for me. thanks !

I like your suggestions, I think they bring more clarity. Thank you!

[jlurien]

Note: I replaced my complete previous comment. The reason is that I hadn't realized that the API has actually a resource noun (device-qos) which makes sense if understood as a short for "device-qos-assignment" or "device-qos-association" or even "device-qos-provision" (the result of a provisioning). The challenge is that this short form has no plural form.

Beyond that the problems to address are more the Schemata names (which can be replaced without impact on API clients), the parameter provisioningId (which can't be changed without a breaking change), and beyond that mostly the descriptions and operationIds which are not referring to the resource which get created, read and deleted. I agree that this shouldn't be done short-term.

The operationIds need to be changed again later, as they should follow the chosen resource name.

In summary I'm fine with the PR, but would propose to add some disclaimer, that it is an initial version and a later version will rename certain operationIds, schemata names and also property names to make it more consistent regarding the actual resources.

BTW: If the API name should be qos-provisioning or qod-provisioning is also worth a discussion. A QoS profile will be provisioned, but not a "QoD" (which is the name of another API which is about has sessions as resource) ... the title of this PR is using "qos-provisioning API" ;-)

I agree that we should rethink about resources and names towards the next meta. Regarding the disclaimer, I assume that that is implicit to an API in initial version. I prefer to think first in what to change and eventually inform in a later meta that we have changed something.

[jlurien]

Note: I replaced my complete previous comment. The reason is that I hadn't realized that the API has actually a resource noun (device-qos) which makes sense if understood as a short for "device-qos-assignment" or "device-qos-association" or even "device-qos-provision" (the result of a provisioning). The challenge is that this short form has no plural form.

"device-qos-association" would be the right resource name for this API IMHO. It took me also a while to understand that that is the actual resource being managed through this API.

When I asked some AI about thi, it suggested terms like "binding", which is the same kind of concept. I agree to find an appropriate name for this link between device and QoS

BTW: If the API name should be qos-provisioning or qod-provisioning is also worth a discussion. A QoS profile will be provisioned, but not a "QoD" (which is the name of another API which is about has sessions as resource) ... the title of this PR is using "qos-provisioning API" ;-)

I agree the usage of "qod" is confusing and should be "qos"

the title of the PR should be qod-provisioning as that is the current name of the API (already edited). I agree that QoS provisioning may make more sense for the API name. The name intended to represent the "provisioning" mode of QoD vs the "session" mode. Both modes deal with QoS on Demand, but "session" mode is more dynamic and connects better with the concept of "on demand", so it would be a good idea to review the provisoning API name

[jlurien]

Changing the operationId will require an update to associated the feature file

@jlurien could you address that within the next two days, so that we get ready for Feb 28th?

Please review if all the comments are addressed. I only did not apply the suggestion for a disclaimer, as I'm not sure where and how to apply that, as no other initial API version has ever had such a disclaimer and we have changed API names, resources and operationIds in other cases.

[RandyLevensalor]

Please review if all the comments are addressed. I only did not apply the suggestion for a disclaimer, as I'm not sure where and how to apply that, as no other initial API version has ever had such a disclaimer and we have changed API names, resources and operationIds in other cases.

@jlurien We applied a disclaimer about some of the l4s attributes in the QoS profile. Here's a link to one of them as an example. https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qos-profiles.yaml#L337

[hdamker]

Please review if all the comments are addressed. I only did not apply the suggestion for a disclaimer, as I'm not sure where and how to apply that, as no other initial API version has ever had such a disclaimer and we have changed API names, resources and operationIds in other cases.

@jlurien First of all: I don't insist on the disclaimer, and I see that the suggestions from @tanjadegroot are applied, so I will approve the PR, just need to go over the result and see if it looks consistent to me.

I get your argument about the initial version - I just think that the situation compared to other APIs is different as we have already at the time of the meta-release a plan for a significant redesign, which I'm not aware of from other examples. One way out of this could be to have soon an alpha version with the changes, so that implementors can decide if they spent the effort for 0.2.0 or are waiting for the next iteration of the API. To allow such different pace and degree of change we should also think about moving qod-provisioning into an own repository.

[hdamker]

The PR looks LGTM, here just a few selection from the suggestions I got from Copilot, which I found valuable for readability.

[jlurien]

Please review if all the comments are addressed. I only did not apply the suggestion for a disclaimer, as I'm not sure where and how to apply that, as no other initial API version has ever had such a disclaimer and we have changed API names, resources and operationIds in other cases.

@jlurien We applied a disclaimer about some of the l4s attributes in the QoS profile. Here's a link to one of them as an example. https://github.com/camaraproject/QualityOnDemand/blob/main/code/API_definitions/qos-profiles.yaml#L337

This is a note on the description of a specific new property introduced in that version, not a general disclaimer advising that paths, operationIds and even the API name can change in a future version.

[jlurien]

Please review if all the comments are addressed. I only did not apply the suggestion for a disclaimer, as I'm not sure where and how to apply that, as no other initial API version has ever had such a disclaimer and we have changed API names, resources and operationIds in other cases.

@jlurien First of all: I don't insist on the disclaimer, and I see that the suggestions from @tanjadegroot are applied, so I will approve the PR, just need to go over the result and see if it looks consistent to me.

I get your argument about the initial version - I just think that the situation compared to other APIs is different as we have already at the time of the meta-release a plan for a significant redesign, which I'm not aware of from other examples. One way out of this could be to have soon an alpha version with the changes, so that implementors can decide if they spent the effort for 0.2.0 or are waiting for the next iteration of the API. To allow such different pace and degree of change we should also think about moving qod-provisioning into an own repository.

Understood. With the new explanations I think that the concepts are much more clear now. The changes being discussed are rather aesthetic, and do not affect that much the logic of the implementation behind, but as soon as we have a decision about better naming we can create a 0.3.0-alpha.1.

Now that we have a different repo for qos-booking, it could make sense to have a separate repo for the provisioning one, as well. We probably had decided to do so initially, if we had the process defined at the time.

[jlurien]

Thanks for the suggestions @hdamker. About the posible disclaimer. If you think it will bring value, we could add it as a note to the readme or release notes while creating the public release PR

[jlurien]

@hdamker let me know if anything else is needed here for the public release PR. I think we still need @RandyLevensalor's approval as he requested changes

[RandyLevensalor]

That looks much better @jlurien

[hdamker]

So we are done here :-)