Subscription & events for Commonalities 0.5.0

[bigludo7]

What type of PR is this?

Add one of the following kinds:

• documentation

What this PR does / why we need it:

This PR covers update to subscriptions & events part for Commonalities 0.5.0

• Resource-based subscription – GET /subscriptions using a 3-legged access token #304
  Resolution: covered in this PR. Make a proposal in new part 11.7
• Resource-based subscription – guidelines for expiration time set by API operator policy #303
  Resolution: covered in this PR
• Make device attribute optional for explicit subscription requests  #300
  Resolution: To be done - seems we have an alignement to make device optional. Direct impact with API misuse #259 - Need to be sync with @eric-murray - aligned with Eric PR Update error codes and info.description template for device / phone number identifiers #324
• Synchronization Status for initialEvent = true notifications #299
  Resolution: covered in this PR. Added a sentence in the yaml and in the DG to clarify us of initialEvent vs subscriptionMaxEvents counting.
• Follow the principle of data minimization for events based on explicit subscriptions #295
  Resolution: Discussion still open in the issue - Adding a section on this topic in the DG document - Check for additional content with @shilpa-padgaonkar. Request with a larger scope than subscriptions
• Support of 504 Exception in Cloud Events Model #291
  Resolution: Waiting for Support & Aligment of 504 Exception in CAMARA APIs  #308 resolution - This one followed by @PedroDiez - Will apply on notification/subscriptions when 308 solved. 504 is not part of the event-subscriptions-template.yaml. From same discussion 415, 500 & 503 removed
• Include Reference Link to CAMARA API Design Guidelines in Notification Cloud Events Artifact #290
  Resolution: Very simple one but need to be done once we split the document. Probably to be removed from this PR as we'll merge this one before the splitting (@rartych - removed from this PR )
• Update the "sink" property description #289
  Resolution: covered in this PR
• Design Guidelines should provide guidance about sinkCredentials in returned/retrieved subscription objects #276
  Resolution: covered in this PR
• How to inform API consumer about unprocessable subscription request in Async mode #243
  Resolution: covered in this PR
• servers field in event-subscription-template.yaml not in line with API guidelines #326

Which issue(s) this PR fixes:

Fixes #

Special notes for reviewers:

Not ready for review

Changelog input

 release-note

Additional documentation

This section can be blank.

docs

[PedroDiez]

18/OCT:

Fine to me so far. Editorial suggestions only

[bigludo7]

18/OCT:

Fine to me so far. Editorial suggestions only

Thanks you Pedro !
Everything considered !!

[bigludo7]

@rartych Points to be discussed in Oct 28th call - given our planning I hope to have resolution quickly to close on this PR:

• Do we remove from the event-subscriptions-template the error 500, 503 and 504? (see discussion Enhancements and Alignments in Errors #321). I tend to think yes given the discussion. It solves Support of 504 Exception in Cloud Events Model #291.
• Do we remove 415 (405 & 406 already removed) ? From the same thread I tend to think yes
• Do we add also in this template the 422 error related to identifier issue? I tend to think yes but indicated in the yaml documentation part that this error are relevant only if an identifier provided by an access token is part of the subscriptions.
• Data minimization (Follow the principle of data minimization for events based on explicit subscriptions #295) - We have triggered a discussion in Device Location (Discuss data minimization for geofencing event DeviceLocation#270) - Could we add more in design guideline than a sentence like: Application of data minimization design must be considered by the API working group for event structure definition.

cc: @PedroDiez @shilpa-padgaonkar

[PedroDiez]

@rartych Points to be discussed in Oct 28th call - given our planning I hope to have resolution quickly to close on this PR:

• Do we remove from the event-subscriptions-template the error 500, 503 and 504? (see discussion Enhancements and Alignments in Errors #321). I tend to think yes given the discussion. It solves Support of 504 Exception in Cloud Events Model #291.
• Do we remove 415 (405 & 406 already removed) ? From the same thread I tend to think yes
• Do we add also in this template the 422 error related to identifier issue? I tend to think yes but indicated in the yaml documentation part that this error are relevant only if an identifier provided by an access token is part of the subscriptions.
• Data minimization (Follow the principle of data minimization for events based on explicit subscriptions #295) - We have triggered a discussion in Device Location (Discuss data minimization for geofencing event DeviceLocation#270) - Could we add more in design guideline than a sentence like: Application of data minimization design must be considered by the API working group for event structure definition.

cc: @PedroDiez @shilpa-padgaonkar

My two cents:

• OK with the first two bullets. With first bullet it is solved Support of 504 Exception in Cloud Events Model #291 and Support & Aligment of 504 Exception in CAMARA APIs  #308
• OK with the third bullet. It is fine to add 422 UNNECESSARY_IDENTIFIER for POST /susbcription.
• For Follow the principle of data minimization for events based on explicit subscriptions #295 I think we have not reached conclusion so far. I would propose to review this PR without considering it and once a conclusion reached about Follow the principle of data minimization for events based on explicit subscriptions #295 cover it in a separate PR

[rartych]

I agree with @PedroDiez proposals
#295 needs to be resolved separately as it can cover not only subscriptions.

[bigludo7]

Hello team (in particular @PedroDiez @rartych @shilpa-padgaonkar )
PR ready for a first review - Thank you for your help

[PedroDiez]

Minor comment

LGTM so far

[PedroDiez]

LGTM at this point

NOTE:

Suggest to set -> x-camara-commonalities: wip as it is ongoing work within the MetaRelease

[rartych]

We have :

       types:
          description: |
            Camara Event types eligible to be delivered by this subscription.
            Note: for the Commonalities meta-release v0.4 we enforce to have only event type per subscription then for following meta-release use of array MUST be decided
             at API project level.
          type: array

I propose to change the note to:
Note: for the current Commonalities version (v0.5) only one event type per subscription is allowed, yet in the following releases use of array of event types SHALL be specified without changing this definition

I am also thinking about including in the template the pattern for event types: org.camaraproject.<api-name>.<api-version>.<event-name>
In Geofencing API we have "#/components/schemas/SubscriptionEventType" and "#/components/schemas/NotificationEventType" used to enumerate event types. But I am not sure if this way should be mandated in the template.
WYDT?

[rartych]

We have:

      discriminator:
        propertyName: "type"
        mapping:
          org.camaraproject.api-name.v0.event-type: "#/components/schemas/Event-typeEvent"
          org.camaraproject.api-name.v0.subscription-ends: "#/components/schemas/EventSubscriptionEnds"

and

    Event-typeEvent:
      description: event structure for event-type event
      allOf:
        - $ref: "#/components/schemas/CloudEvent"
        - type: object

Event-typeEvent is not pure camelCase, so I propose to change it to something like ApiSpecificEvent or EventApiSpecific (compatible with EventSubscriptionEnds) or similar.
Then in mapping we would have something like:

        mapping:
          org.camaraproject.api-name.v0.api-event: "#/components/schemas/EventApiSpecific"

I would be good to indicate that multiple API specific event types can be used.

[bigludo7]

Thanks @rartych for your review.
I've took all you comments:

• Add 2 exemples of event type instead of 1 to explicit that an API can manage several event type
• Add a note for event type name convention
• Aligned event type example name
• Event type in subscription managed in an enumeration

[PedroDiez]

NOTES:

• Pending to remove 415, 500, 503 Errors

[bigludo7]

NOTES:

• Pending to remove 415, 500, 503 Errors

Done ! 415, 500 & 503 removed.

[PedroDiez]

LGTM

[patrice-conil]

LGTM