Update the subscription models to align on CAMARA commonalities

[maxl2287]

What type of PR is this?

Add one of the following kinds:

• correction
• enhancement/feature

What this PR does / why we need it:

Update of the subscription-models based on:

• https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#12-subscription-notification--event
• https://github.com/camaraproject/Commonalities/blob/main/artifacts/camara-cloudevents/event-subscription-template.yaml

Which issue(s) this PR fixes:

Fixes #162

[akoshunyadi]

The base url should be with apiName, so 'device-' is missing.. (I can't comment there directly)

[sachinvodafone]

As per today discussion over subscription response, would apprecaite if we can include examples in specification that pointed in discussion

[bigludo7]

@maxl2287 I have a second thought about making the device identifier optional in the subscription. My point is the following: For the POST that's fine to not have this device identifier as we have it thru the access token.

But, when the developer check the subscription 10 days later, in the GET /subscriptions response better to have this device identifier present because without it impossible to know what device is targeted....

So... either 1/ we keep the device mandatory or 2/we make it optionnal for the POST request but mandatory in the GET response

I prefer 1/ but perhaps we can have other solution.

cc: @fernandopradocabrillo

[maxl2287]

@maxl2287 I have a second thought about making the device identifier optional in the subscription. My point is the following: For the POST that's fine to not have this device identifier as we have it thru the access token.

But, when the developer check the subscription 10 days later, in the GET /subscriptions response better to have this device identifier present because without it impossible to know what device is targeted....

So... either 1/ we keep the device mandatory or 2/we make it optionnal for the POST request but mandatory in the GET response

I prefer 1/ but perhaps we can have other solution.

cc: @fernandopradocabrillo

@bigludo7 I aggree also on letting it mandatory here.

[maxl2287]

As per today discussion over subscription response, would apprecaite if we can include examples in specification that pointed in discussion

@sachinvodafone I have added three examples for GET /subscriptions/{subscriptionId} pointing to specific status of the subscription.

[sachinvodafone]

As per today discussion over subscription response, would apprecaite if we can include examples in specification that pointed in discussion

@sachinvodafone I have added three examples for GET /subscriptions/{subscriptionId} pointing to specific status of the subscription.

Thanks @maxl2287 , Can we get an example for "GET /subscriptions" where we provide only the subscriptionID for subscriptions with incomplete asynchronous calls and show the full response for the others (synchronous)?

[maxl2287]

Thanks @maxl2287 , Can we get an example for "GET /subscriptions" where we provide only the subscriptionID for subscriptions with incomplete asynchronous calls and show the full response for the others (synchronous)?

@sachinvodafone However, this will not align with the specified response for GET /subscriptions. The response for this endpoint includes a list of only having Subscription components.

There should not be a mix of Subscription objects and subscriptionId values within the same list.

[bigludo7]

@maxl2287 I have a second thought about making the device identifier optional in the subscription. My point is the following: For the POST that's fine to not have this device identifier as we have it thru the access token. But, when the developer check the subscription 10 days later, in the GET /subscriptions response better to have this device identifier present because without it impossible to know what device is targeted.... So... either 1/ we keep the device mandatory or 2/we make it optionnal for the POST request but mandatory in the GET response I prefer 1/ but perhaps we can have other solution. cc: @fernandopradocabrillo

@bigludo7 I aggree also on letting it mandatory here.

I suggest we do this way - let keep it mandatory. If in future we shift to optional this is not a breaking change.

[sachinvodafone]

Thanks @maxl2287 , Can we get an example for "GET /subscriptions" where we provide only the subscriptionID for subscriptions with incomplete asynchronous calls and show the full response for the others (synchronous)?

@sachinvodafone However, this will not align with the specified response for GET /subscriptions. The response for this endpoint includes a list of only having Subscription components.

There should not be a mix of Subscription objects and subscriptionId values within the same list.

@maxl2287 I understand your point that it will only include those subscriptions that have already been created. Thank you.

[maxl2287]

Thanks @maxl2287 , Can we get an example for "GET /subscriptions" where we provide only the subscriptionID for subscriptions with incomplete asynchronous calls and show the full response for the others (synchronous)?

@sachinvodafone However, this will not align with the specified response for GET /subscriptions. The response for this endpoint includes a list of only having Subscription components. There should not be a mix of Subscription objects and subscriptionId values within the same list.

@maxl2287 I understand your point that it will only include those subscriptions that have already been created. Thank you.

@sachinvodafone yes, but to be more precise: The list includes every subscription, which was created by the user, even those which are still in the creation process (see status ACTIVATION_REQUESTED).

[sachinvodafone]

Thanks @maxl2287 , Can we get an example for "GET /subscriptions" where we provide only the subscriptionID for subscriptions with incomplete asynchronous calls and show the full response for the others (synchronous)?

@sachinvodafone However, this will not align with the specified response for GET /subscriptions. The response for this endpoint includes a list of only having Subscription components. There should not be a mix of Subscription objects and subscriptionId values within the same list.

@maxl2287 I understand your point that it will only include those subscriptions that have already been created. Thank you.

@sachinvodafone yes, but to be more precise: The list includes every subscription, which was created by the user, even those which are still in the creation process (see status ACTIVATION_REQUESTED).

Suppose if we have only one subscription and that is asynchronous which still not completed, in this case ,we will get "ACTIVATION_REQUESTED" if user try for "GET /Subscriptions" . If Yes, then I am having another question.

[maxl2287]

Suppose if we have only one subscription and that is asynchronous which still not completed, in this case ,we will get "ACTIVATION_REQUESTED" if user try for "GET /Subscriptions" . If Yes, then I am having another question.

You will receive something like:

[
  {
    "sink": "https://endpoint.example.com/sink",
    "sinkCredential": {},
    "types": [
      "string"
    ],
    "config": {
      "subscriptionDetail": {
        "device": {
          "phoneNumber": "+123456789",
          "networkAccessIdentifier": "123456789@domain.com",
          "ipv4Address": {
            "publicAddress": "84.125.93.10",
            "publicPort": 59765
          },
          "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
        }
      },
      "subscriptionExpireTime": "2023-01-17T13:18:23.682Z",
      "subscriptionMaxEvents": 5,
      "initialEvent": true
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "startsAt": "2024-07-04T11:44:36.664Z",
    "expiresAt": "2024-07-04T11:44:36.664Z",
    "status": "ACTIVATION_REQUESTED"
  }
]

[sachinvodafone]

Suppose if we have only one subscription and that is asynchronous which still not completed, in this case ,we will get "ACTIVATION_REQUESTED" if user try for "GET /Subscriptions" . If Yes, then I am having another question.

You will receive something like:

[
  {
    "sink": "https://endpoint.example.com/sink",
    "sinkCredential": {},
    "types": [
      "string"
    ],
    "config": {
      "subscriptionDetail": {
        "device": {
          "phoneNumber": "+123456789",
          "networkAccessIdentifier": "123456789@domain.com",
          "ipv4Address": {
            "publicAddress": "84.125.93.10",
            "publicPort": 59765
          },
          "ipv6Address": "2001:db8:85a3:8d3:1319:8a2e:370:7344"
        }
      },
      "subscriptionExpireTime": "2023-01-17T13:18:23.682Z",
      "subscriptionMaxEvents": 5,
      "initialEvent": true
    },
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "startsAt": "2024-07-04T11:44:36.664Z",
    "expiresAt": "2024-07-04T11:44:36.664Z",
    "status": "ACTIVATION_REQUESTED"
  }
]

I have updated the scenario in discussion board here

[maxl2287]

@bigludo7 can we do here a final review? I just have added some examples based on @sachinvodafone's feedback.

[bigludo7]

@bigludo7 can we do here a final review? I just have added some examples based on @sachinvodafone's feedback.

Thanks @maxl2287 - Look good for me. Let's get final review from @sachinvodafone and @akoshunyadi and we're good to go.

[bigludo7]

@sachinvodafone it is ok for you now? Looking for you thumb up to merge :) Thanks