Use of CloudEvent in Instance-based (implicit) subscription

[rkandoi]

Problem description

The current guidelines for subscriptions and events (link) requires the use of CloudEvents in the resource based (explicit) subscriptions.

However, there is no mention of CloudEvents in the instance based subscription.

Expected action

We would like to enquire if this means CloudEvents are NOT allowed to be used in the instance based subscription. If yes, why?

On the other hand, if there is no such rule, we would like to recommend adding a statement that "instance based subscriptions may or may not use CloudEvent depending on the API Sub Project preferences"

Additional context

Given that an API can support only one or both subscription models - we think it is easier for the application developer calling an API to have the same notification format, regardless of whether an implicit or explicit model is used.

[hdamker]

@rkandoi It might be not obvious and could be made clearer, but the chapter 12.2. Event notification is not limited to explicit subscriptions but is also valid for implicit subscriptions. With that CloudEvent is the mandatory event notification format in CAMARA.

Consequently all APIs which have currently implicit subscriptions defined (carrier-billing, quality-on-demand, qod-provisioning) are using the CloudEvent structure as their notification format in the newer releases.

If you have a proposal to make these facts clearer it might make sense to propose that.

[rkandoi]

@hdamker Thank you for the prompt reply.

One idea to avoid this (potential) confusion could to be move the text below from "resource based subscriptions", directly under Section 12 which introduces the functionality.

"CAMARA subscription model leverages CloudEvents and is based on release 0.1-wip as it is a vendor-neutral specification for defining the format of subscription. A generic neutral CloudEvent subscription OpenAPI specification is available in Commonalities/artifacts/camara-cloudevents directory (event-subscription-template.yaml)."

I can create a PR if that makes sense.

[hdamker]

@rkandoi For 0.5.0 it might be too late. And for the following version there is anyway some restructuring planned.
@rartych @bigludo7 would a PR on the current document still make sense?

[rartych]

One idea to avoid this (potential) confusion could to be move the text below from "resource based subscriptions", directly under Section 12 which introduces the functionality.

"CAMARA subscription model leverages CloudEvents and is based on release 0.1-wip as it is a vendor-neutral specification for defining the format of subscription. A generic neutral CloudEvent subscription OpenAPI specification is available in Commonalities/artifacts/camara-cloudevents directory (event-subscription-template.yaml)."

Although it may be not clear (hence the planned document restructuring) it is correct:

• explicit subscriptions are based on CloudEvents Subscription API 0.1-wip - it is extension of CloudEvents defining mechanism to subscribe to events;
• instance-based subscriptions are created together with other resources, so there is only guidance on needed parameters to create subscription no dedicated mechanism is needed;
• CAMARA event notification leverages CloudEvents and is based on release 1.0.2 - all notifications should follow it as a specification for describing event data in a common way.

Any help on improving clarity and readability of Design guidelines is welcome, rather for the next version.