The problem of handling time zones in Web APIs properly comes up from the following scenario:
You have an application that has functionalities connected with date and time.
You have one user using your mobile app in Paris, all the dates they see should be in their local time zone, meaning GMT+2.
You have another user using your web app in Moscow, again, all the dates they see should be in their local time, meaning GMT+3.
The question now is how do you store these dates in your database, and at what point in time do you convert them into the users’ desired time zones?
The confusion here comes where you get one request in the API from the mobile app client in Paris that has
datetime value of 1 Oct 2022 12:00, and you get another request from the web app client in Moscow that has
datetime value of 1 Oct 2022 13:00, but they both refer to the same point in time, just in a different time zone.
The solution to this problem is to store the
datetime in UTC, do all the business logic inside the API in UTC as well, and leave the responsibility of localizing the time to the client apps.
I will break down the implementation in two parts in order to make it easier to digest.
First Part: Getting the
datetime to be UTC when it arrives in the API
As I said before, the responsibility of converting the
datetime to UTC should be left to the client-side applications, so before sending any
datetime to the API the client should convert it to an ISO-8601 UTC string and have the API only accept ISO-8601 formatted UTC strings for
datetime in all of the requests.
yyyy-MM-dd'T'HH:mm:ssZ) – is preferred because it’s human-readable and it omits milliseconds precision in order to enable decent sorting and comparison performances.
Second Part: Returning the
datetime to the client and displaying it in local time.
This part is easier when it comes down to implementation, your API should return the ISO-8601 string of the UTC
datetime that is stored in the database, and then the client app would be responsible for localizing that
datetime. Most of the common Web / Mobile UI frameworks support conversion of UTC to the user’s local time, so that should not be an issue.
UML flow diagram
Here is a diagram of one request flow so that all this comes together.
An alternative solution to handling time zones in web APIs
An alternative solution is to have the client apps send the
datetime with a stamp including the UTC offset from the client’s local time zone. Again, following the standard ISO-8601, the following times all refer to the same moment: “18:30Z”, “22:30+04”, “1130−0700”, and “15:00−03:30”.
Once the request
datetime is being stamped on the client-side, the server would be responsible for implementing a request filter in order to do the conversion for each date as it arrives.
Conclusion for handling time zones in web APIs
Either way you solve it, you will end up with a UTC
datetime in your API. You can do calculations with it, store it or query it against previously-stored UTC dates, and as long as you add proper UTC validation to your API, your worry of handling time zones in Web APIs should be gone.
More on Software Engineering