Provides specific CAMARA OAS for notification event

[bigludo7]

Prepared with @patrice-conil
As we are offering “notification event” for a lot of our API we need to clarify the technical assets. As of today, we are defining the notification event in the same OAS than the ‘nominal’ API resource itself. It could trigger confusion as it mixes endpoint provided by server from the notification endpoint that must be on client listener side.

Our proposal is

• to provide a separate OAS only describing the notification endpoint. We’ll provided here generic CAMARA event notification structure. This swagger will be available to app developer to generate their listener endpoint.
• To describe event notification API per API in the callback structure (as done in QoS).

[shilpa-padgaonkar]

camaraproject/WorkingGroups#260

[shilpa-padgaonkar]

@bigludo7 : For a generic Camara wide event structure, cloudevents spec (https://github.com/cloudevents/spec/tree/main) and https://github.com/cloudevents/spec/blob/main/subscriptions/spec.md#33-http-binding-for-the-subscription-api could be worth a look

[patrice-conil]

Hi @shilpa-padgaonkar,
Thanx for the link, we will use it if workgroup members adhere to the idea.
Another point to discuss this friday.

BR,
Patrice

[shilpa-padgaonkar]

For those not familiar with CloudEvents might want to look here : https://github.com/cloudevents/spec/blob/main/cloudevents/primer.md

[bigludo7]

@shilpa-padgaonkar @patrice-conil To make progress on this topic I've contributed a proposal for a generic notification OAS (#41 ). I keep aligned with the API design guideline document.

[jgarciahospital]

Please considere this message as a formal inclusion of the GSMA OGW Product WS request to include Subscription/notification mechanism as part of OGW services. Some examples of those are attached, and will be also requested when and if affected.

The request includes both the formalization of the creation in Commonalities of a subscription/notification mechanism generic for OGW services, as agreed by GSMA OGW Product WS, and also the inclusion of each spscific funcionality in each already existing API. Others may be applied, and others may apply in future drops/releases.

Additional context
More details included in the formal request file, attached:

Camara Submission - Subscription_Notifications v2.docx

[gregory1g]

@jgarciahospital few suggestions:

1. application must be able to, at least, terminate its subscription (better adjust it), not just create
2. MNO should also notify the application about events related to the subscription. For example, if the person closed their contract or changed the number, currently active subscription makes no sense anymore.

[bigludo7]

Thanks for the feedbacks.
@jgarciahospital
The notification model has been introduced for CAMARA API for some months now and it is already available in few Camara APIs like Qod, Carrier Billing, Device Status. The word document you provided is very good material to update what we have currently implemented or in process of implementing. I propose to take a look & to redistribute this per API CAMARA.

@gregory1g
Capability to terminate subscription & event related to subscription management are already available - This is described in the API Design guideline document and implemented in Device status API.

BTW, I recommend that we stick to the original topic of this conversation: the format of the notification send back to the listener once event occurred to avoid mixing different topic. Of course new issue are awelcome.

[PedroDiez]

Hi all,

@bigludo7
if i understand well, proposal is to define a common /traversal OAS3 API to cover this functionality https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#122-event-notification

[bigludo7]

@PedroDiez Yes !

[jgarciahospital]

Thanks for the feedbacks. @jgarciahospital The notification model has been introduced for CAMARA API for some months now and it is already available in few Camara APIs like Qod, Carrier Billing, Device Status. The word document you provided is very good material to update what we have currently implemented or in process of implementing. I propose to take a look & to redistribute this per API CAMARA.

BTW, I recommend that we stick to the original topic of this conversation: the format of the notification send back to the listener once event occurred to avoid mixing different topic. Of course new issue are awelcome.

Thanks Ludovic, we've already openned or commented to confirm the request per API.

[hdamker]

I had a closer look into CloudEvent primer and was impressed by the design thoughts which went into it and the wide adoption – it kept stable since 2019, and there is a complete eco-system of SDKs etc around. It' a CNCF incubated project, so already a kind of de-facto standard.

So, yes, we should definitely evaluate and follow this spec instead of spending further time to improve and formalize ( our own and being just another [incompatible webhook] (https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/primer.md#normalizing-webhooks) format into the world.

The differences of CloudEvent to our current guideline are not significant, but subtle, and there are also some points which should be reconsidered. E.g. the three layers of eventNotification, event and eventDetails. Also the subscriptionId on level of transport outside the event does not make sense for me (and does not fit what we need for implicit subscriptions in QoD).

And as they are so similar, there is no reason why we should have a different definition for events and its metadata in CAMARA – it wouldn’t be developer friendly to don’t allow developers to use the existing implementations, SDKs, bindings etc of CloudEvents. Also we would jeopardize any attempt to get “Cloud Native” in the sense of LF/CNCF.

Therefore I propose to do first a short evaluation before we rush forward with our "proprietary one". And I hope that we can conclude on this existing standard. It is now the time to do it, before the APIs are leaving the pre-production stage.

[patrice-conil]

Hi @hdamker,
I thought we didn't have time to do this now. But if so then I totally agree with you.
Do you want me to update our proposal (@bigludo7 and me) to reflect these changes in #41?
Could you handle updating the guidelines in parallel to open discussion with all contributors?

[shilpa-padgaonkar]

@patrice-conil : I see that the PR #41 has in its heading WIP but is not created as a draft PR. If the PR is not ready to be reviewed, would you mind changing it to draft PR instead?

[patrice-conil]

Sorry @shilpa-padgaonkar,
it's my mistake.
You can review it.

[shilpa-padgaonkar]

As there seems to be now an agreement, for evaluation, I can see this issue include several PRs:
Some of the obvious ones I have listed below:

1. Original PR Add generic notification OAS file #41

2. New PR showing how a cloud-events based solution could look like Define CAMARA Event using cloudevents in OAS notification #43

3. A PR to add description in guidelines document about how we will incorporate the CloudEvents spec for our Camara APIs. Which optional parts in the spec will be relevant for us.

This evaluation will help us decide if our approach is sustainable long term ( where we can imagine messages being delivered not just using http protocol but may be even kafka or other standards).

[rartych]

There is dedicated guideline document for delivering notifications with Cloudevents: Web Hooks for Event Delivery.

Regardless results of evaluation section 4. Abuse Protection provides important security recommendations that should be considered in CAMARA.

[PedroDiez]

Hi all,

Think missing some part of the context.

The point here is for everybody to comment about the preference of which model to follow? Whether based in PR#41 or PR#43?
cc @patrice-conil @shilpa-padgaonkar

[patrice-conil]

Hi @PedroDiez,
Yes, we can discuss/comment both proposals here.

[PedroDiez]

Feedback from TEF:

• Currently our model is closer to PR#41 proposed model.
• Anyway, move towards CloudEvents model is something it can be achieved.

Then, if there is a preference to go for CloudEvents Model, it is also OK from our side.