Closed NoelWirzius closed 9 months ago
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 (https://github.com/camaraproject/WorkingGroups/issues/156) and I'm looking for feedback. Thanks
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.
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 )
@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.
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
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.)
@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.
@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:
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 (https://github.com/camaraproject/WorkingGroups/issues/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.
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
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?
@bigludo7 For any (read only) boolean status, there are indeed two use cases that can be supported:
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.
@eric-murray We have similar conversation in Device Location (here https://github.com/camaraproject/DeviceLocation/pull/27#issuecomment-1461937858)
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
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.
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:
POST /roaming
allowing both 'fire & forget' and subscription request. 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 https://github.com/camaraproject/DeviceLocation/pull/27. This is important, for developer sake, that we have same 'construction' in all our CAMARA API.
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:
Roaming status
Association status (IMSI-Device relation)
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.
@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.
@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: https://github.com/camaraproject/DeviceLocation/pull/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.
@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.
@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 https://github.com/camaraproject/WorkingGroups/issues/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.
For the proposal to add a location event type I have created a new issue https://github.com/camaraproject/DeviceLocation/issues/40. Will be important to align cross DeviceStatus and DeviceLocation groups to get an aligned API behavior.
Hello For information and review --> https://github.com/camaraproject/WorkingGroups/pull/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.
please check this and provide feedback https://github.com/camaraproject/Commonalities/issues/8#issuecomment-1629615969
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.
https://github.com/camaraproject/Commonalities/issues/8#issuecomment-1642419272
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
@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.
@NoelWirzius all regarding PRs with following features have been merged:
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.
With all the update on the API (see https://github.com/camaraproject/DeviceStatus/pull/87) I guess we can close this issue
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
/Subscriptions
LOSS_OF_CONNECTIVITY
UE_REACHABILITY
ROAMING_STATUS
expireTime