Time frame text description needs a bit more attention

[gregory1g]

Problem description The API description includes the following text: _"The starttime and endtime need to follow the following constraints

• The parameter starttime is recommended not to be earlier than 7 days from the current time.
• It is recommended not to exceed 1 day between the starttime and endtime
• The parameters starttime and endtime cannot be passed separately. Either both are passed or neither is passed.If both startTime and endTime are not passed, in actual calculation, considering that devices in idle state cannot be counted, a default time interval needs to be pushed forward from the current time, which is recommended to be 10 minutes
• If a device seen in different cells in the queried time interval (Endtime- StartTime), the last cell of the device should be returned . The device should be counted under the last seen cell."_

This text has the following issues: 1) It confuses API definition and implementation recommendations. 2) "following constraints" list contains recommendations, not constraints. One can ignore these recommendation completely 3) default values for start and end time should be defined on API level 4) Reasons behind "7 days", "not to exceed 1 day" and "10 minutes" are not mentioned. While these limits are far from obvious. 5) the most important: this texts anchors the API to the "cell-based" logic and accuracy. The API must not be limited to this implementation logic, therefore "cell" here must be replaced with an "area", Like "The device should be counted under the last seen area." 6) "If a device seen in different cells in the queried time interval (Endtime- StartTime), the last cell of the device should be returned" is misleading - the API does not return cell for a devices.

[bigludo7]

I'm aligned with @gregory1g that we need a bit to rework this. We should avoid any mention to cell and instead use area.

I'm also a bit uncomfortable with the use of "the number of switch" in the API doc. For me we're counting the number of device.

I'm also wondering if from a business & technical perspective getting the number of device connected now for a given area is not a different thing that getting the number of devices that was connected at least one time on an area between Aug 26th 00:00 and Aug 26th 13:59. This is perhaps 2 distinct APIs; The second one can evolve with additional data.

I think UC are different, getting history it tougher technically and will not be marketed same.

Happy to discuss this in our meeting.

[chinaunicomyangfan]

@gregory1g Thank you for your suggestion. I agree with your point of view.

2."following constraints" list contains recommendations, not constraints. One can ignore these recommendation completely 3.default values for start and end time should be defined on API level 4.Reasons behind "7 days", "not to exceed 1 day" and "10 minutes" are not mentioned. While these limits are far from obvious.

Currently, only the relevant constraints have been mentioned in the description. If everyone thinks it's okay, I will add relevant constraints at the API level in the future, such as using error codes or default values.

• If a device seen in different cells in the queried time interval (Endtime- StartTime), the last cell of the device should be returned . The device should be counted under the last seen cell."

There should be one more matter to discuss in this sentence,

1. If the device appears in this area at least once at a specified time, it should be counted.
2. Device is counted in the last appearing area.

I think the first option is more reasonable.