We save all our datetime data on database in UTC (a timestamp with time zone column in postgresql).
Assuming "America/Sao_Paulo" timezone, if a user saves an event "A" to the database at 2021-08-24 22:00:00 (local time) this will be converted to UTC and saved as 2021-08-25 01:00:00.
So, we are wondering what would be the best way (here "the best way" refers to the developer experience) to consume an API where is possible to filter events by start and end date.
Imagine the following situation: the user is on the website and needs to generate a report with all events that happened on 2021-08-24 (local time America/Sao_Paulo). For this, the user fills start and end date both with 2021-08-24.
If the website forwards this request directly to the API, the server will receive the same date provided by the user and some outcomes can happen:
- If the server does not apply any transformation at all, the data returned will not contain the event "A" — by the user perspective, this is wrong.
- The server can assume that the date is in UTC and transform start date to
2021-08-24 00:00:00and end date to2021-08-24 23:59:59. Then, apply the timezone of the user, generating:2021-08-24 03:00:00and2021-08-25 02:59:59. Filtering the database now would bring the expected event "A". - The API itself could expected a start and end datetime in UTC. This way, the developer can apply the user timezone on client side and then forward to server (
2021-08-24T03:00:00Zand2021-08-25T02:59:59Z). - The API itself could expected a start and end datetime either in UTC or in with the supplied offset (
2021-08-24T00:00:00-03:00and2021-08-24T23:59:59-03:00). Github does it this way.
What got us thinking was that a lot of APIs accept only a date part on a range filter (like the github API). So, are those APIs filtering the data in the client timezone or they assume the client knows the equivalent UTC date that they should filter by (we could not find any documentation that explains how github deals with an incoming date only filter)?
For us, makes more sense the date filter consider the timezone of the client and not leave to them the burden to know the equivalent UTC datetime of the saved event. But this complicates a bit the filtering logic. To facilitate the filter logic, we thought that maybe have another column on database to also save the local datetime of the event (or only the local date) would be interesting. Is this a valid approach? Do you know any drawbacks?
*We know that on a database perspective, it is recommended to save datetime in UTC (not always, as showed here) but in our case this seems to only make things more difficult when handling API consumption.
*It is importante to know that, when saving an event, the user cannot provide when it happens, we always assume the event happens in the moment it is being saved.