Add generic notification OAS file

[bigludo7]

What type of PR is this?

Add one of the following kinds:

• enhancement/feature

What this PR does / why we need it:

Add generic notification OAS file
open for discussion.

Which issue(s) this PR fixes:

Fixes #8

Special notes for reviewers:

Changelog input

Additional documentation

[shilpa-padgaonkar]

@bigludo7 : Thanks for the PR contribution.

Under the #8 I had suggested ( #8 (comment) ) the use of CloudEvents as we are now moving towards a more generic way on how to handle events in Camara.

Is there a reason why we try to redefine Event in Camara and not use an industry standard like CloudEvents or a generic way to subscribe (https://github.com/cloudevents/spec/blob/main/subscriptions/subscriptions-openapi.yaml)

It would be great to know if we have already identified shortcomings in the CloudEvents spec and hence made the decision to define our own new way in Camara.

[bigludo7]

@shilpa-padgaonkar
Thanks for the feedback. Yes I checked your comment but I was thinking this is a completely new pattern from the one we have already described in the guidelines.

My proposal target is to be aligned with the guideline and particularly with already subscription/notification designed in our API.

[patrice-conil]

Hi @shilpa-padgaonkar,
@bigludo7's proposal helps consumers of our already defined APIs to implement the /eventNotifications endpoint on their side.
It doesn't impact the design of existing APIs, so I think it's a good starting point.
The CloudEvent format is very interesting but requires global approval from CAMARA partners as it introduces breaking changes.

[hdamker]

@bigludo7 @patrice-conil Please see first my comment on the issue #8.

I don't want to comment on this PR here in detail as I think we shouldn't finalize it. But if then there are several open points which need to be clarified:

• Security schema: why three-legged?
  • In addition there are two schema defined but only one used
  • And do we really expect an API consumer to provide an Oauth token server to be able to use the APIs?
  • If I don’t remember it wrong we concluded on relaxed requirements for the bearer token
• Version number mismatch between version in file name and within file
  • Version number in filename? (Could make sense, but have we agreed on that?)
• Inefficient, unnecessary additional layer of “eventNotification”, which would conflict with CloudEvent, and does not fit to implicit subscriptions (where the additional layer is completely empty)

Especially solving the last point and the general need to have a future proof design which does not only fit to webhooks are points which are easier to solve by adapting an existing industry standard like CloudEvents then to spend here the time just to have a CAMARA proprietary "standard". Otherwise we are missing our aim for developer friendly APIs.

[PedroDiez]

This endpoint is the one indicated vía {$request.body#/webhook/notificationUrl}.
Then, it is not really required to append "/eventNotifications"

So maybe we can agree on indicating like:
/{$request.body#/webhook/notificationUrl}

And in the description comment:

INFORMATIVE ENDPOINT. The value of this endpoint is freely declared by each client app by means of resource-based subscription or instance-based subscription. /{$request.body#/webhook/notificationUrl} is just a convention naming referring to an absolute URL, indeed the one indicated by API client in the triggering of the procedure (resource-based or instance-based).

[patrice-conil]

Hi @PedroDiez,
Thanks for your comments.
As this is a generic OAS, we can't refer to {$request.body#/webhook/notificationUrl} that doesn't exists in this context, I'll replace it by /your_webhook_notificationUrl and include your description in #43

[PedroDiez]

Hi @patrice-conil
Have seen the update in PR#43, I think it would apply in the same fashion in this PR, isn't?

[patrice-conil]

Hi @PedroDiez,
yes, but I'm waiting for a decision before reporting in this PR.

[PedroDiez]

maybe rename to "sendNotification"

[patrice-conil]

Done 😄 in #43

[patrice-conil]

@PedroDiez, @shilpa-padgaonkar, @rartych,
Awaiting a decision on which format to include before reporting from #43 in this PR

[bigludo7]

Close PR has the guideline proposal will promote use of Cloud event format