Review comments on API definition content

[tanjadegroot]

Problem description
Some comments on the API content that I cam across

Possible evolution

• MiB, GiB: I was not familiar with these terms and looked on Internet for explanations: https://www.techtarget.com/searchstorage/definition/mebibyte-MiB. Question: do we really need the technical precision of the binary system in this API or would the decimal system be enough ? the article states that the binary system is not much used in commercial contexts, so the decimal system might be more developer-friendly". Personally I heve never seen any user data plans expressed in the binary system. If you keep it It would be good to add an explanation and a link to the ISO/IEC definition or https://en.wikipedia.org/wiki/Binary_prefix
• event type names: from the event type only it is not obvious if they concern the remaining data volume or the used data volume: for the 50/75/90, it would be more clear to rename them to "data-used-90-percent", etc. (iso "data-90-percent".
• the check API is not fully clear. One part seems to be about checking that a certain volume is still available (which has nothing to do with thresholds as such) an which is already covered by the /retrieve API, while another part seems to want to check the usage versus the thresholds somehow. In several descriptions a "requested threshold" is mentioned, while the threshold is not a parameter/entity in the request body.
• is the DataVolumeCategory really needed ? Using an ENUM seems to limit the usability of the API, as well as being a bit arbitrary), while just a unit and an integer value (as done in volumeToCheck) could be enough and more flexible, so just a schema called "DataVolume" could serve both purposes. For the unit, also the above "MiB/GiB" question applies (as opposed to more usual "MB"/"GB" units)
• customer: lines 25 and 26 should refer to the "API consumer", not the "customer". In line 5, I would rephrase "the customer's data usage" to "an end-user's data usage"

[eric-murray]

Hi @tanjadegroot

Thanks for the thorough review! We'll discuss these points during the next Device Status meeting.

Regarding MiB / MB and GiB / GB, when network operators advertise MB and GB, they almost certainly mean a power of 2 (2^20 and 2^30 in this case). Let's take Vodafone as an example:

How we charge for data usage
We measure your data usage in kilobyte (KB). Data is based on the following units:
• 1024 KB = 1 Megabyte (MB)
• 1024 MB = 1 Gigabyte (GB).

So 1 "MB" is 2^10 x 1 KB, and 1 "GB" is 2^10 x 1 "MB". They do not define 1 "KB", but almost certainly mean 1024 bytes.

These definitions of KB, MB and GB originated in JEDEC (intended for RAM sizing), but are now superseded by the IEC definitions of KiB, MiB and GiB. Unfortunately, both standards are proprietary and must be purchased, which is not ideal for an open source project.

If we can agree that "powers of 2" are indeed required here, my preference is to use the modern (future proof) terms, particularly as the JEDEC terminology is ambiguous, and can be interpreted as SI "powers of 10". By using "MiB" and "GiB", we can ensure no misinterpretation by the API consumer, even if they do need to read our documentation to understand what the terms mean. If they see "MB" and "GB", they will not read the documentation, but will instead interpret those terms according to their current (mis)understanding.

[tanjadegroot]

I agree fully that the MiB/GiB is more accurate and future proof, but the Vodafone example shows that a user only sees MB/GB (while the values are actually MiB/GiB) :-) So the 2 systems are being mixed when addressing an end-user.

I am fine if you want to keep the MiB/GiB, but a bit more documentation in the info.description field on that may then be helpful.
It could just be by adding a sentence like "The "MiB"/"GIB" units are the more accurate versions of where generally "MB"/"GB" is used when referring to data plans" or something to that extend.

Thanks for discussing the other comments :-)

[eric-murray]

I created sub-issues for each issue identified