Update API guidelines to add subscription/notification/event.md

[bigludo7]

Added chapter 12 about Subscription, Notification & Event management to get team feedbacks.
Fixes #156

[hdamker]

Seems that the PR includes also the changes from #171 ... I suppose these should go seperate.

[bigludo7]

@hdamker Yes correct. My assumption was : this PR #173 will take time while the PR #171 should be quickly merged as we got already a discussion and a vote.
Perhaps I took a wrong approach with this assumption?

[PedroDiez]

Yes, I think this PR will take more time than PR #171

[PedroDiez]

Initial review

[bigludo7]

Update following @PedroDiez @akoshunyadi comments, in particular for

• POST Subscriptions simplification
• additional information fir TERMINATION_END
• aligned name for type/eventType

[bigludo7]

@PedroDiez @akoshunyadi & other interested... I have updated the document according to your valuable comments - Could you please take a look ?
If there is still pending issue requiring update before publication please let me me know and I will set up an ad hoc call to discuss & resolve these points.
Thanks

[PedroDiez]

Seems Ludovic due to latest change format is altered:

[sachinvodafone]

If the event triggers the termination of the subscription , I believe , using an HTTP DELETE request to remove the subscription is good idea rather "POST".

[bigludo7]

@sachinvodafone Here the notification did not trigger the termination. The notification informs the subscriber that the subscription is terminated. So this is an event and as such we use the POST notification operation.
Of course to delete a subscription we have the DELETE /event-subscriptions.

[sachinvodafone]

The subject of "Example for subscription termination - Request:" was causing me confusion, but I find it acceptable if its purpose is only to inform the client about a termination that has already been executed/terminated through another action. Thank you.

[bigludo7]

Fixed example formatting

[bigludo7]

Fixed example formatting

[sfnuser]

Looks good to me.

[PedroDiez]

LGTM - Status reached on 12/May

[PedroDiez]

LGTM

[jordonezlucena]

If finally merged, don't forget to decide how to tag the change in the guidelines, either with "evolution", "new considerations" or "breaking", according to the discussion in #170

[bigludo7]

@jordonezlucena What concretely we need to go before to merge ?
Here we're introducing breaking change but as we do not have (yet) versioning on the guideline document I'm not sure to understand what to do. Thanks for your guidance.

[jordonezlucena]

@jordonezlucena What concretely we need to go before to merge ?
Here we're introducing breaking change but as we do not have (yet) versioning on the guideline document I'm not sure to understand what to do. Thanks for your guidance.

As for the WoW on versioning, TEF proposal is as follows:

• In API-design-guidelines.md, defining/enabling a versioning section that allows specifying the concrete version the guidelines doc referrs to.
• Creating a separate folder for each defined version, and uploading the corresponding doc there.

As for the actual PR#173, TEF proposal is as follows:

• Before PR#173 merging, set guidelines doc with v0.9
• After PR#137 merging, set guidelines doc with v1.0 and tag the versioning change with label = "evolution" (we don't see it as a breaking change, since today's guidelines do not capture anything related to notifications).

Finally, every API version (defined and maintained in the corresponding Sub-Project) should reference which version of the guidelines doc is built on.

[bigludo7]

Thanks @jordonezlucena - make sense for me and I'm fine to tag as evolution.

We still need few adjustement with @rartych proposal here: n #170. We need to decide:

• Do we rename in Archive the document with the name extended with date e.g.: API-design-guidelines-19_05_2023.md or with version number as you mention?
• Do we track modification in a section of the document itself or in a separate file (like API-design-guidelines-changelog.md)

I do not see there sensitive points (as long as we we have separate file each distinct version and a change log 'somewhere' I'm fine) but before to proceed PR I prefer we get complete alignment.

Could we merge this and take care about Guidelines versioning after this merge?

[bigludo7]

Agreed with "Evolution" tag
@rartych up to you to merge ;)

[rartych]

As agreed the PR will merged and the versioning decided in Issue #170