Aligned notifications with guideline

[akoshunyadi]

What type of PR is this?

Add one of the following kinds:

• correction

What this PR does / why we need it:

Update of the notification event related fields based on the API design guideline

Which issue(s) this PR fixes:

Fixes #154

Special notes for reviewers:

Changelog input

Update of the notification event related fields based on the API design guideline

Additional documentation

[hdamker]

Have added some suggestions for reviews, especially @eric-murray @bigludo7 and @sfnuser who were involved within the definition of the chapter in the guideline document.

[bigludo7]

Very good aligned with subscription & notification guideline.

[sfnuser]

@akoshunyadi Thanks. Looks good.

One comment - As we have added notificationAuthToken, should we remove apiKey security scheme? However, I wonder what could be the appropriate securitySchemes we could specify for notification - perhaps {} & bearerAuth?

[jlurien]

• Event has to be remodeled with discriminator at the right level
• We have to adapt callback to the new strcture:

paths:
  /sessions:
    post:
...
      callbacks:
        notifications:
          "{$request.body#/weebhook/notificationUrl}":
            ...

I also think we are not specifying the callback correctly since the beginning. The POST /notification operation must not be at first level of /paths, but within the POST /sessions callbacks, as indicated in https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/callback-example.yaml

[akoshunyadi]

• We have to adapt callback to the new strcture:

paths:
  /sessions:
    post:
...
      callbacks:
        notifications:
          "{$request.body#/weebhook/notificationUrl}":
            ...

I also think we are not specifying the callback correctly since the beginning. The POST /notification operation must not be at first level of /paths, but within the POST /sessions callbacks, as indicated in https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v3.0/callback-example.yaml

@jlurien I think your both points are valid. Putting /notification below the POST /sessions decreases the chance for misinterpretation of the /notification endpoint

[emil-cheung]

@akoshunyadi Thanks. Looks good.

One comment - As we have added notificationAuthToken, should we remove apiKey security scheme? However, I wonder what could be the appropriate securitySchemes we could specify for notification - perhaps {} & bearerAuth?

Probably keep API Key but carried by header instead of query string.
I have created an issue about it #157

[akoshunyadi]

@patrice-conil any preference from Orange?

[hdamker]

any preference from Orange?

@bigludo7 @patrice-conil the question at hand is if it is also from your perspective ok to omit apiKey completely from the spec (as we discussed in today's call). The notion is that this would be in line with the new design guidelines for notifications.

[emil-cheung]

@akoshunyadi Thanks. Looks good.
One comment - As we have added notificationAuthToken, should we remove apiKey security scheme? However, I wonder what could be the appropriate securitySchemes we could specify for notification - perhaps {} & bearerAuth?

Probably keep API Key but carried by header instead of query string. I have created an issue about it #157

According to the community discussion, please remove API key.

[patrice-conil]

@hdamker, we are ok to remove apiKey, notificationAuthToken will be fine.

[eric-murray]

apiKey definition in components remains, but is now unused. This should also be deleted.

[sfnuser]

Thanks @akoshunyadi. Updated comments

[hdamker]

@akoshunyadi with the merge of #138 we have now some merge conflicts. May I ask you to rebase?

[hdamker]

@bigludo7 @eric-murray @jlurien @sfnuser From my point of view we are done. Can you please see if your comments are done and confirm with an approval?

[jlurien]

LGTM

[hdamker]

/LGTM - thanks @akoshunyadi for the rebase.