Create initial version

[akoshunyadi]

Problem description
Create initial version based on https://github.com/camaraproject/APIBacklog/blob/main/documentation/API%20proposals/APIProposal_Device_Connection_Quality_Indicator.md

Input:

• Device Availability: CONNECTED / NOT_CONNECTED
• Network Insights: https://github.com/camaraproject/ConnectivityInsights
• Network type: 2g/3g/4g/5g
• Remaining data volume of the contract: <200MB/<1GB/...
• Speed limitations of the contract: ?

Possible evolution
Provide OAS file(s)

Alternative solution

Additional context

[akoshunyadi]

I think it would make a sense to first discuss and agree here on the general functionality e.g. endpoints and data in & out

[akoshunyadi]

As I understand, something like this is required:

base path: device-quality-indicator

POST /retrieve
Request:

• device

Response:

• enum of predefined categories

POST /subscriptions
Request:

• device
• enum of predefined categories, when changing to the specific category or on all changes

Questions:

• Can we map all the inputs into a single value, e.g. 1-10?
• Do we need 3-legged auth?

[sachinvodafone]

Just checking , whether it's better to have one consolidated endpoint (/retrieve) that provides all information like "network-status" and "congestion-history" etc in a single response, or whether it's more efficient to separate these concerns into multiple endpoints (e.g., one for real-time status and another for historical congestion data).

[VijayKesharwani]

@akoshunyadi Could you also confirm whether the following two things should be included in this API or not, as they will be available in the DeviceDataVolume API as well I guess?

1. Remaining data volume of the contract: <200MB/<1GB/...
2. Speed limitations of the contract: ?

[VijayKesharwani]

@akoshunyadi I also wanted to ask if I should create two separate MRs: one for the /retrieve endpoint and another for the /subscriptions endpoint. This would make it easier to review them individually. Please let me know your thoughts.

[akoshunyadi]

@akoshunyadi Could you also confirm whether the following two things should be included in this API or not, as they will be available in the DeviceDataVolume API as well I guess?

1. Remaining data volume of the contract: <200MB/<1GB/...

2. Speed limitations of the contract: ?

Yes, that's our requirement. DeviceDataVolume is clear, that's the other new API we should work on. About Speed limitations of the contract I don't have informations yet.

[akoshunyadi]

@akoshunyadi I also wanted to ask if I should create two separate MRs: one for the /retrieve endpoint and another for the /subscriptions endpoint. This would make it easier to review them individually. Please let me know your thoughts.

I would prefer 1 PR, that's easier to keep in sync, because similar changes may be necessary in both, after the reviews.
But first we should agree here, how the API should work. How to combine these inputs? I mean creating an OAS which just returns a number, it's easy, but that doesn't solve the problem.

[akoshunyadi]

To summarize the current ideas:

1. API provides one magic number to describe the device connectivity => difficult to do the calculation, and to make it transparent for the customer
2. API provides each value of the input APIs separately => no extra value added, the evaluation has to be done on customer side
3. API provides "device connectivity potential" with indication of "where are we now" and what would be possible, e.g. a range

[akoshunyadi]

@NoelWirzius Could you please provide some input regarding use cases and what kind of response is expected from the product management view? Is something like idea#3 in #6 (comment) imaginable?

[eric-murray]

I've rather neglected this issue, so will give my thoughts before the meeting tomorrow:

• I think we should start with a "simple" scoring system, where a device gets allocated "points" according to the status of the different factors that contribute to the overall score. So, for example, it might get 2 points for being connected to 2G, 4 points for 3G, 8 points for 4G and 10 points for 5G. Other factors would have their own scoring system.
• Maximum score for a device that gets "top marks" in all factors should be 100. This is the "gold standard" device, and a device's actual score is thus relative to this gold standard.
• There should be a second "optimised" score, which is the score the device could have if all factors that could be optimised were optimised. For example, if the device was connected to 2G, but could be connected to 4G (because the device supports it and it is available locally to the device) but not 5G (because either the device does not support it, or it is not available locally), then the "optimised" score for that factor would be 8 points, compared to 2 for the "current" score. But if the device is at the edge of any coverage and signal strength low, that generally can't be optimised for the device's current location, so that score doesn't change.

So, for example, one device might get a "current" score of 20 but an "optimised" score of 80, which tells us that that device would benefit from being optimised. But another device might have a "current" score of 20 but an "optimised" score of only 30, so maybe it is time to buy a new device, or move somewhere that the mobile signal strength is better.

Additional thoughts:

• Scoring system would need to evolve as technology evolves (i.e. as the "gold standard" evolves), but that could be done slowly over time by updating the algorithm periodically. So a device might get a score of 80 now, but in 3 years time only get a score of 60 for the same factors.
• The different factors generally don't compensate for each other. For example, being connected to 2G can't be compensated for by having a high data allowance. So I don't think we can simply add up all the points a device gets. Some element of multiplication is required so that, for example, a device that is not connected at all, or has no data allowance left, gets 0 points irrespective of other factors.

I'll continue to think on what the different "factors" should be, and how the factor scores can be combined within the constraints of a minimum overall score of 0 and a maximum of 100.