A solution for handling time zones in Web APIs

clocks of cities

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

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

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.

The Implementation

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.

ISO-8601 format(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