Subscription Mode with new Eventtypes

[NoelWirzius]

Summary

In this issue will add a new path which enables subscription mode. On top of this is the enablement of new events and the multiple handling of devices and events.

Due to this it is possible to get more informations about a device based on a subscription level. There are several Use-Cases like Streaming and Fraud where a "push" from the network can trigger events on the application sides

Changes

• Adding new Path /Subscriptions
  • Eventtypes
  • LOSS_OF_CONNECTIVITY
    • This will give back if the device is loosing the connection to the network (SMS/DATA)
  • UE_REACHABILITY
    • This will give back when a device is gaining connection to the network
  • ROAMING_STATUS
    * Informs when roaming status changed
  • Attributes
    • expireTime
      • Defines how long the subscription should run
  • Multiple Devices
    • Enable to set subscription directly for a complete list of identifiers
  • Multiple Eventtypes
    • Enable to set subscription for identifiers to multiple events

[bigludo7]

Hello @NoelWirzius
I'm interested to contribute for this issue to improve the current API with adding notification support.

About the event, I've raised an issue in commonalities to unify the event structure (camaraproject/WorkingGroups#156) and I'm looking for feedback.
Thanks

[eric-murray]

I disagree with the proposed approach in PR #28. There is already a POST \roaming path defined, so why not allow the client to specify whether they want an immediate response or to set-up an ongoing subscription? This could be determined explicitly (e.g. via a flag) or implicitly (e.g. given the presence or absence of subscription parameters). Immediate response returns 200 and subscription returns 201.

This also keeps open the option to have additional statuses in different YAMLs.

[bigludo7]

Hello @eric-murray

Thanks for your review!

For me this is distinct requirement - and distinct services from Telco monetization perspective - between managing one-time request/response to an event-base request that could stay 'alive' for a long time (based on the subscriptionExpireTime).

We are working with this approach in the device location API where you can query a device location now or subscribe to get notification when the device entered/left an area.

I'm not sure to get your point about : This also keeps open the option to have additional statuses in different YAMLs. you mean managing loss of connectivity and reachability in another swagger?

Let's continue the discussion and waiting for other feedback - probably we can tab a discussion for our next meeting (March 15th )

[eric-murray]

@bigludo7

I agree with the requirement for APIs such as this one to support the subscription/notification model, I just disagree with the approach of having separate paths for immediate response or creating a subscription. They could be the same path (in this case POST /roaming), in exactly the same way as it is a common path for the NEF T8 interface.

If this is a common requirement across multiple APIs, then perhaps a common approach should be agreed (in Commonalities) and then applied to all the relevant APIs.

I'm not sure to get your point about : This also keeps open the option to have additional statuses in different YAMLs. you mean managing loss of connectivity and reachability in another swagger?

This was a point raised by Telefonica (@monamok), who expressed the opinion that additional statuses could be published as separate YAML files to reduce individual file complexity. It was agreed to not to make a decision on this at this stage, as only one status is currently supported.

[eric-murray]

Here's an example of how RequestRoamingStatus could be modified to allow optional subscription creation within the /roaming path. Note that the subscription parameter is optional.

RequestRoamingStatus:
  type: object
  properties:
    ueId:
      $ref: '#/components/schemas/UeId'
    uePort:
      $ref: '#/components/schemas/Port'
    subscription:
      $ref: '#/components/schemas/SubscriptionInfo'
  required:
    - ueId
SubscriptionInfo:
  type: object
  properties:
    notification_url:
      type: string
    notification_auth_token:
      type: string
    subscription_expire_time:
      type: string
      format: date-time
  required:
   - notification_url
   - notification_auth_token
   - subscription_expire_time

[bigludo7]

Thanks @eric-murray,

Technically I'm fine with the model you suggested.

From a business perspective, I think the monetization will differ from one time request to a subscription that why I prefer the model with distinct resource, as it is more explicit from a client perspective, but ... probably a matter of "taste and colors". Let's see the feedback from other folks involved in this API (@NoelWirzius @monamok etc.)

[eric-murray]

@bigludo7

Monetisation will depend largely on the response - clients cannot reasonably be charged if the response is a 4XX or 5XX error. In this case, a single status request will be a 200 and a subscription creation 201, so the distinction will be clear to any charging and billing system. Charging per notification is straightforward.

However, I agree that if we want to, for example, allow a client to request single status reports but not set-up subscriptions, then separate paths are preferable. But what if we want to allow them to create subscriptions for roaming status, but not other statuses? Analysis of the request contents and not just the path will always be required for some access and charging models.

But I agree in general that business models are a factor in API design.

[bigludo7]

@eric-murray

In this case, a single status request will be a 200 and a subscription creation 201

Agree ...but for you, in the 201 (subscription created) I guess we will also provide current situation for roaming and reachability in the response?

But what if we want to allow them to create subscriptions for roaming status, but not other statuses? Analysis of the request contents and not just the path will always be required for some access and charging models.

Yes this is a fair point and the aggregated subscription is probably not a good design.

If we get back to the 'service' we want to offer - from a 'feature' perspective we have following:

Fire & forget request:
1- Is mobile is now reachable (by text or/and SMS) ? [in order to simplify from our API consumer we can perhaps merge REACHABILITY & LOSS_OF_CONNECTIVITY in one aggregated service ?]
2- Is mobile is now in roaming situation? (and if yes which operator is visited)

Subscription request
3- I want to be notified each time the mobile is reachable or loss connectivity [I assume we can also merge here REACHABILITY & LOSS_OF_CONNECTIVITY but this is challengeable]
4- I want to be notified each time the mobile is 'moving' in roaming on/off

The questions now:

• Are we agree on this feature list?
• Are we wanting to have all these feature in one API ?
• Are we wanting to have one endpoint covering both the Fire&Forget and Subscription (1&3) (2&4) ?

[monamok]

Hello,

If this is a common requirement across multiple APIs, then perhaps a common approach should be agreed (in Commonalities) and then applied to all the relevant APIs.

I agree with @eric-murray and maybe we should wait to see what other participants say about the issue @bigludo7 opened (camaraproject/WorkingGroups#156) and then decide how to adapt our solution here.
But in the meantime, I'd just like to point out that if we go with a dedicated endpoint to create subscriptions, we should only include Roaming in the events list as it's the only functionality that is currentley available in the API. For other events such as connectivity and reachability I guess we should first see if we want to include them here and how, and then see how to manage event subscriptions. It doesn't make sense to provide subsriptions for event types that their status are not included in the API yet.

[bigludo7]

Thanks @monamok
For the event, yes let's wait for the commonalities discussion.

For the introduction of reachability/connectivity as additional feature of this API this is up to the "Device Status team" to decide, correct?
--> we could discusss this in our next meeting March 15th perhaps.

My view is to provide in this APIs following capabilities:

Fire & forget request:
1- Is mobile is now reachable (by text or/and SMS) ? [in order to simplify from our API consumer we can perhaps merge REACHABILITY & LOSS_OF_CONNECTIVITY in one aggregated service ?]
2- Is mobile is now in roaming situation? (and if yes which operator is visited) (already provided)
Subscription request
3- I want to be notified each time the mobile is reachable or loss connectivity [I assume we can also merge here REACHABILITY & LOSS_OF_CONNECTIVITY but this is challengeable]
4- I want to be notified each time the mobile is 'moving' in roaming on/off

[monamok]

Thanks @bigludo7

For the introduction of reachability/connectivity as additional feature of this API this is up to the "Device Status team" to decide, correct?
--> we could discusss this in our next meeting March 15th perhaps.

Sure, we can discuss it in our next meeting but the point here is also to decide when we want to close the scope and have a v1.0? If we leave the scope open, we can keep adding new functionalities to it. But when is gonna be the moment we decide we have enough functionalities and we're going to have a first oficial version?

[eric-murray]

@bigludo7
For any (read only) boolean status, there are indeed two use cases that can be supported:

• Return the current state
• Send a notification whenever the state changes

So, yes, these use cases should be supported for all statuses that can be expressed as a boolean.

When a subscription is created, the current status can be included in the 201 response. This can be optional (maybe the client sets a flag if they want the value included), but I think it simpler just to include it automatically.

[bigludo7]

@eric-murray
We have similar conversation in Device Location (here camaraproject/DeviceLocation#27 (comment))

One good argument for having different endpoint for fire&forget request from subscription request: we need to provide capabilities for API client to unsubscribe (and consequently to retrieve them).

If we keep only one resource we have a POST /Roaming but also we will have a DELETE /Roaming and GET /Roaming. For me this is a issue because this is confusing. What do you think?

Thanks

[eric-murray]

Hi @bigludo7

3GPP have a different model - everything is a subscription, but you can request an "immediate response", in which case you get the answer in the response and the subscription is "ephemeral" (i.e. doesn't exist after you get the response).

So, different models, different advantages and disadvantages. It would be good to get the opinion of our mythical "developer". I suspect developers who understand subscriptions would also find it easy to understand "one shot" ephemeral subscriptions. However, developers who do not understand subscriptions might indeed be confused about all the different verbs that we attach to the /roaming path if that was done. But I also think that is the wrong approach. It should be:

GET /subscriptions/roaming
GET /subscription/roaming/{subscription_id}
POST /roaming
DELETE /subscription/roaming/{subscription_id}

So a developer not interested in or understanding subscriptions would ignore the /subscription paths and head to POST /roaming if they wanted roaming status. Developers who understood subscriptions would expect POST /roaming to be where they started (even if they wanted immediate response).

My intuition is that it will be the more "professional" developers using the Device Status APIs. These APIs will not be called from some app on a smartphone or a web browser script, but from 3rd-party business applications, such as banking or insurance. But I don't think there is a right or wrong answer here - just different approaches.

[bigludo7]

Thanks @eric-murray
For me, in the 3GPP , it is not so ephemeral because you can request maximumNumberOfReports or monitorExpireTime - the subscription may live for long time but it is not manageable.

I understood your proposal with the /subscription path and it makes completely sense for me.

We're closing gaps - There is still one remaining:

• You're in favor of a POST /roaming allowing both 'fire & forget' and subscription request.
• I will prefer to have separate path POST /roaming for 'fire & forget' and then POST /subscription/roaming for subscription.

But agreed that none of them is wrong - both works.

As I proposed to have something on the guideline on this topic I would like to get view from https://github.com/maxl2287 and https://github.com/jlurien as we are tackling same topic here camaraproject/DeviceLocation#27. This is important, for developer sake, that we have same 'construction' in all our CAMARA API.

[JoachimDahlgren]

We are pleased to follow the discussion and this issue and support the proposed extensions and are interested in contributing the Device Status API.

In addition to the initial proposal on UE_REACHABILITY and LOSS_OF_CONNECTIVITY we propose to also add location, association status and First time connect to the API.

As for

Fire & forget request:
1- Is mobile is now reachable (by text or/and SMS) ? [in order to simplify from our API consumer we can perhaps merge REACHABILITY & LOSS_OF_CONNECTIVITY in one aggregated service ?]

Subscription request
3- I want to be notified each time the mobile is reachable or loss connectivity [I assume we can also merge here REACHABILITY & LOSS_OF_CONNECTIVITY but this is challengeable]
4- I want to be notified each time the mobile is 'moving' in roaming on/off

We agree on the proposed simplification to use the UE_REACHABILITY and LOSS_OF CONNECTIVITY into one (as well as considering also COMMUNICATION FAILURE as a source of information for reachability). This would simplify for the API user, not the least when subscribing as UE_REACHABILITY will only report the positive case.

We also agree that it would be valuable to be able to subscribe to Device Status changes. In addition we propose to do this in a way that allow an "all-in-one subscription" operation, that is supports to subscribe to multiple device information event types in one subscription. The reasoning behind is to make it easier for the developer to set-up and manage subscriptions that covers many device statuses. For instance set up a single subscription for a UE covering roaming, reachability and location.

We have looked at the 3GPP where as Eric points out

everything is a subscription, but you can request an "immediate response", in which case you get the answer in the response and the subscription is "ephemeral" (i.e. doesn't exist after you get the response).

We do however find the 3GPP model to be a complicated model for the developer as even if you do a one time subscription you do not always get a result back in the response but need to be prepared to handle events. This behavior should rather be encapsulated by the CAMARA layer.

We also believe that for most events from the underlying network CAMARA need to do a translation to easier to understand events and filter away not needed information

To summarize our view, we propose the Device Status API to include

Query the information of a single device:

1. Location

• Reported in form of geographical coordinates (as developers will have no use of getting back an identity such as for instance CellId)
• Point or shape.
• Need to be under consent management control

2. Reachability status

• Simplified reporting in form of Status unknown, Not connected, Connected
• Hide the complexity of underlying monitoring events

3. Roaming status

4. Association status (IMSI-Device relation)

• Association exists. This status occurs in query result only.
• No association. This status occurs in query result only.

5. Subscribe to information changes of a single device or a group of devices:

• Location – Event triggered at change of location. In form of geographical coordinates. Point or shape.
• Reachability status – Event triggered for when status change from connected/not connected
• Roaming status
• Association status (IMSI-Device relation) - Association has been changed. This status occurs in event notification only.
• First time connect to the network (Only applicable for subscription)

6. Cancel the device information subscription

This we propose to realized as:

GET /devices/{deviceId}/status/roaming
GET /devices/{deviceId}/status/reachability
GET /devices/{deviceId}/status/device-association
GET /devices/{deviceId}/status/location
POST /device-information-subscription
DELETE /device-information-subscription/{subscriptionId}

If wanted we can provide a YAML file for further clarity and details.

[eric-murray]

@JoachimDahlgren
Unfortunately your proposal does not comply with the CAMARA API Design Guidelines. Please have a look through these.

I was not proposing that CAMARA copy the 3GPP subscription model directly, but am rather using it as an example to show that ongoing and ephemeral "one shot" subscriptions can be supported via the same path and is not an outlandish proposal. More generally. given that the NEF is likely to be the network element that is used to implement device status APIs, some consideration should be given to how that supports subscriptions, particularly if we can avoid stateful behaviour in the API gateway itself.

@bigludo7
Indeed, either POST /roaming or POST /subscription/roaming could be used to create the subscription. My thought is that the request bodies would essential be the same apart from the inclusion or otherwise of the subscription parameters. A common path might open the developer's eyes to the possibility of subscriptions where they had not previously considered them ("What are these optional subscription parameters all about?"), when otherwise they might ignore subscriptions and use an inefficient solution, such as status polling.

A final point to raise (that you will be well aware of but others might not) is that the topic of a unified approach to subscriptions / notifications is an issue within Commonalities. Whether developers will be more confused by one or other approach to subscriptions is worth debating, but they will certainly be confused if different CAMARA APIs adopt different approaches.

[bigludo7]

@JoachimDahlgren Thanks for your contribution.
In this group we're working only on the status part so your points 2 & 3.

For the location (point 1) we're working on it here: camaraproject/DeviceLocation#27
For the Association status (point 4) it should probably be tracked here : https://github.com/camaraproject/SimSwap (TBC)

For the point 5 & 6 this is relevant for all subscription and probably we should handle them in Commonalities.
I should confess I'm bit nervous about handling multiple request in one shot because as we have to check/get consent things could become complicated (but I understood UC).

@eric-murray I can probably update the PR to check if we're inline - not to be approved but to have a swagger example of our progress.

To be sure about your last point: we have today some notification that are strictly linked to one action request for Carrier Billing Payment and QoD; The notification is provided to track the lifecyle of an entity instance (a payment, a QoD session). This why the notification is part of the action request (Customer will pay for a QOD session or a payment - not to get notification about their status)
While here, or, in Device location tracking, the notification is the request itself - this is what we will sell.
Hope this is the point you mentioned.

[eric-murray]

@bigludo7
Yes, different APIs will have different requirements regarding subscriptions / notifications. My point was that, where there is scope for a common approach or methodology, that should be adopted to make life simpler for developers, and the place to discuss this is Commonalities.

So whilst requirements for subscriptions / notifications for the Device Status API can be discussed here, the mechanism(s) to enable this should be at least informed by the conclusions and recommendations reached within Commonalities.

[bigludo7]

@eric-murray

So whilst requirements for subscriptions / notifications for the Device Status API can be discussed here, the mechanism(s) to enable this should be at least informed by the conclusions and recommendations reached within Commonalities.

Fully agreed. I will provide a proposal in commonalities (I have raised camaraproject/WorkingGroups#156) - I will use what we're crafting there. Latest PR is not for merging but to check if we're aligned with this model for commonalities proposal. Thanks.

[JoachimDahlgren]

For the proposal to add a location event type I have created a new issue camaraproject/DeviceLocation#40. Will be important to align cross DeviceStatus and DeviceLocation groups to get an aligned API behavior.

[bigludo7]

Hello
For information and review --> camaraproject/WorkingGroups#173

@JoachimDahlgren I would like to add you as reviewer in the commonalities to get your view but I was not able to add you. It did not prevent you to comment there.

[shilpa-padgaonkar]

please check this and provide feedback camaraproject/Commonalities#8 (comment)

[jgarciahospital]

Please considere this message as a formal inclusion of the GSMA OGW Product WS request to include Subscription/notification mechanism as part of OGW services.

camaraproject/Commonalities#8 (comment)

For the specific case of device status, multiple examples of use cases are proposed with reference to proposals on input-output for such services, to be aligned with current subscription mechanism in this API.

Additional context
More details included in the formal request file, attached:
Camara Submission - Subscription_Notifications v2.docx

[bigludo7]

@jgarciahospital We have integrate the roaming event in current version and there is a PR open for the documentation. I'v added you as reviewer to be sure we're aligned.

[akoshunyadi]

@NoelWirzius
all regarding PRs with following features have been merged:

• /subscriptions endpoint
• roaming events
• connectivity events
• subscription expire time

The support for multiple devices in one API wasn't implemented, there were concerns about consent etc. However it would be just a comfort feature anyway.
I suggest to close this issue and open a new one with only that topic, if needed.

[bigludo7]

With all the update on the API (see #87) I guess we can close this issue