search

camaraproject / RegionDeviceCount

Repository to describe, develop, document and test the RegionDeviceCount API family
Apache License 2.0
0 stars 2 forks source link

A developer friendly and clear statement abut data returned by the API is needed #8

Open gregory1g opened 2 months ago

gregory1g commented 2 months ago

Problem description "the number of switch on users" is: confusing for application developers. 1) what is a switch? 2) who is a user? 3) what does "on users" really mean?

Expected behavior The description must clearly specify what exactly is counted using application developers friendly language For example:

bigludo7 commented 2 months ago

Agree with @gregory1g As discussed during our meeting probably connected devices will be better.

Regarding the API name perhaps we need to think about changing it.

chinaunicomyangfan commented 2 months ago

I think we have reached a preliminary agreement. Due to the inability to confirm the number of users, it was mentioned in the meeting that changing the name of the API to Region Device Count would be more appropriate. If there are no different opinions, I will submit this proposal to TSC this Friday and close this issue.

gregory1g commented 2 months ago

"Region Device Count" is good, "Region Sim Count" could be a bit more accurate. A device is a phone, drone, watch etc. One device can have multiple SIMs inside (theoretically all SIMs can be from the same MNO) and API will count SIMs, not devices they are "put in".

chinaunicomyangfan commented 2 months ago

"Region Device Count" is good, "Region Sim Count" could be a bit more accurate. A device is a phone, drone, watch etc. One device can have multiple SIMs inside (theoretically all SIMs can be from the same MNO) and API will count SIMs, not devices they are "put in".

I agree, the Region SIM count is indeed more accurate, but is it too technical? It may not be easy for users to understand. I hope everyone can provide feedback or submit it to TSC for selection (I am not sure if they will help us choose)

bigludo7 commented 2 months ago

Both of your comment make sense :) .... SIM is more accurate while device is more understandable. I have a very small preference for device but will follow team preference. Let's get our preference in this group and then we expose it to the TSC.

bigludo7 commented 2 months ago

I have another question/comment - If we agreed that we count the SIM (whatever we use SIM or Device in the API Name) do we need to allow requester to make distinction between SIM for direct user device (phone, weareable) vs IoT device?

I'm looking to the UC provided by @chinaunicomyangfan - in particular the User Story 1 - I tend to think that we are looking here for 'human' associated with device but not IoT device. WDYT?

gregory1g commented 2 months ago

I would say that for both UC the API should offer a filter. This way API user can specify what type of devices is needed. This is especially important for advertisement user story. One can start with simple filter like human/IoT, roamers/local. But design the filter so that it can be extended in the future.

bigludo7 commented 2 months ago

Yes ! I got also the comment about counting or not the roamers ;)

chinaunicomyangfan commented 2 months ago

@bigludo7 @gregory1g Thank you for your suggestion. This is also the topic I plan to discuss. The Region User Count API has some mature usage scenarios in our internal products. Currently, in our internal use, we provide the following response parameters to meet the needs of different scenarios: total users, 5G users, 4G users, 23G users, IoT users, mobile users, roaming users, and local users. I think it makes sense to return by user classification. Further discussion may be needed on which categories are necessary. In my opinion, distinguishing between humans and IoT devices is necessary for User Story 1, and distinguishing between roaming and local may be necessary for advertising scenarios.

gregory1g commented 2 months ago

Let me add two ideas for the discussion: 1) the filter must be extendable and flexible. 2) the API must not be limited to listed 2 scenarios exclusively. Advertisement is one of the use cases, and this use case can benefit mostly any filtering option and combinations.

Therefore, I suggest to consider a filter which: 1) allows apply different criteria independently - like 5G and roamers 2) allows introduction of new filtering criteria (like smartphone type - Android/iOS) in the future in a backward compatible way

chinaunicomyangfan commented 2 months ago

Let me add two ideas for the discussion:

  1. the filter must be extendable and flexible.
  2. the API must not be limited to listed 2 scenarios exclusively. Advertisement is one of the use cases, and this use case can benefit mostly any filtering option and combinations.

Therefore, I suggest to consider a filter which:

  1. allows apply different criteria independently - like 5G and roamers
  2. allows introduction of new filtering criteria (like smartphone type - Android/iOS) in the future in a backward compatible way @gregory1g excellent idea,so do you have any suggestions for request or response parameters
bigludo7 commented 1 month ago

Pinging here @hdamker for guidance :) Herbert, if we want to switch API name from RegionUserCount to RegionDeviceCount what is the process? From this WG team this latest name reflects more the API intent.

hdamker commented 1 month ago

Herbert, if we want to switch API name from RegionUserCount to RegionDeviceCount what is the process? From this WG team this latest name reflects more the API intent.

I would say that this is mainly a topic to align with APIBacklog:

For TSC I would consider it enough if APIBacklog is informing about the change.

chinaunicomyangfan commented 1 month ago

Herbert, if we want to switch API name from RegionUserCount to RegionDeviceCount what is the process? From this WG team this latest name reflects more the API intent.

I would say that this is mainly a topic to align with APIBacklog:

  • Open an issue within APIBacklog - the table there need to be updated and the new name should be communication properly towards GSMA OGW Product team
  • Potentially PR on APIproposal_RegionUserCount_ChinaUnicom.md if there are more changes then just the name, e.g. regarding the scope

For TSC I would consider it enough if APIBacklog is informing about the change.

Thank you Herbert,Do you mean we should communicate with GSMA OGW Product team first?

hdamker commented 1 month ago

Just saying that both, APIBacklog and OGW Product team, need to be involved/informed (as it was a proposal coming with one of the OGW drops). I have no specific opinion about the sequence.

bigludo7 commented 1 month ago

@chinaunicomyangfan @hdamker Thanks Herbert To sum-up:

@chinaunicomyangfan I let you triggering this ? (I can help but will be off 17 to 26th May).

chinaunicomyangfan commented 1 month ago

@bigludo7 Thank you, I will handle it. Have a nice vacation

chinaunicomyangfan commented 1 month ago

email to GSMA has been sent and Helene suggested us to submit issue and PR to API Backlog. so the issue has been submitted here.

Issue & PR in https://github.com/camaraproject/APIBacklog An email to GSMA product stream leaders : Helene Vigue & Olu Omobitan