Proposal to split QoS Sessions and QoS Profiles into two separate API definitions

[hdamker]

Problem description

We have currently within the QoD API (v0.10.0) two different resources:

• name: QoS Sessions
  description: Manage QoS sessions
• name: QoS Profiles
  description: Manage QoS Profiles

There are several arguments why it would make sense to split the API in two separate ones:

• QoS Profiles could be used also in other use case (see comment below from @jlurien)
• QoS Sessions and QoS Profiles will (most) probably have different security and privacy requirements. Having them together within one API won't allow to use a "wildcard" scope across the complete API
• Operators who plan to offer only a small set of well-known QoS Profiles might want to decide to not implement QoS Profiles (at least initially). Currently that would lead to a partially implementation of the QoD API.
• The implementation of QoS Sessions and QoS Profiles might be based on different network and/or service components (e.g. service catalog), potentially implement by diffferent teams
• The current YAML is long and difficult to maintain (definitions for QoS Sessions and QoS Profiles are mixed up)

Possible evolution

Split the current API definition into two different
"QoS Sessions on Demand" (to be discussed to keep in the basepath qod for backward compatibility)
"QoS Profiles"

Potentially define a YAML with common definitions between the APIs (if not already available within https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml)

Alternative solution

?

Additional context

From discussion within #244:

For applying scopes which allow the "wildcard" scope we might need also to think about splitting sessions and profiles in two APIs.

Splitting the API may have all sense. BTW, we are facing some new use cases where QoS profiles may be used by other APIs as well, so that would ease reusing this functionality.

Originally posted by @jlurien in #244 (comment)

[jlurien]

For scope management it also makes sense to split the current API in 2, as QoS Profiles has no Personal Information, and QoS Profiles may be used in other APIs, not only for QoD sessions.

[hdamker]

QoD Call Feb 19th: Agreed to split the APIs

Additionally discussed:

• Common schema should be defined only once in a common file, either in sub project or from Commonalities
  • Process and script needed to create one bundled specification file for distribution (run after every merge)
  • To be discussed: use of (which) released version from Commonalities

[jlurien]

@hdamker do you think we can propose a PR already, or should we discuss further on the additional points?

I would approach the task as:

• We can start with a first PR at WG level, splitting the current spec in 3 files:
  • qod-sessions.yaml, with all operations tagged as QoD Sessions,
  • qod-profiles.yaml, with all operations tagged as QoD Profiles,
  • qod-common.yaml, with the shared schemas
• We can decide if we move some common components to Commonalities in a subsequent step
• The script to generate a bundled spec can be tackled later as well

[jlurien]

I started with this task. The key point to discuss is which basePath and API version is applied tor each split API:

• For qod-sessions.yaml:
  a) We keep qod and v0.11.0
  b) We change to qod-sessions with same or other versioning

• For qod-profiles,yaml:

  • New basePath qod-profiles or other?
  • Which version: 0.1.0 as first one, or 0.11.0 to remark it's a split

This is to be agreed prior to the PR

[hdamker]

Results from discussion of the above issue within the QoD Call on March 22nd: 

• qos-profiles agreed for the profiles (not qod-profiles)
• v0.11.0 agreed as version for both APIs (as the same functionality was already available as and in v0.10.0)
• Basepath for "qod-sessions" requires further discussion, options discussed so far:
  • qod (as of today)
  • qod-sessions
  • qos-sessions
  • quality-on-demand (long form of qod)

Request for action: please raise your opinion regarding the right basepath here in the issue

[jlurien]

We have to decide also the title for the split yaml, which currently is "QoD for enhanced communication". It should be aligned with the baseBath, so we may choose "Quality on Demand" for the title, and quality-on-demand for the basePath

But if we are moving to an approach where we have more granular APIs, as we are keeping only the endpoints under the tag "QoS sessions", another option would be qos-sessions, and call the new split API "QoS sessions"

So maybe deciding on the API title is more relevant.