When designing APIs and data models, I prefer simplicity and avoid ambiguity.
For date and time, programmers like using epoch time. This is the number of seconds or milliseconds since January 1, 1970. It requires just one integer field, making it easy to compare and manipulate.
My favourite geek joke is that the world should switch from measuring time in hours and months to using megaseconds and gigaseconds.
We accept UTC only?
APIs are often crafted by backend developers who aim for simplicity. Sending epoch times as integers might be harsh. However, even if using the more human-readable ISO string format (YYYY-MM-DDTHH....), requiring all time fields to be in UTC is just shifting responsibility onto others.
Relying on the client to handle time zone conversion can lead to issues, especially if the time is entered by users via a GUI.
Even if your backend only works in a single timezone, your users might be in different time zones.
People think in local time, not UTC. If the frontend provides UTC time, it drops the timezone information. Later, when displaying stored UTC time, the frontend must guess the timezone. An incorrect guess can confuse users.
A client device's timezone setting might be wrong, so your application shouldn't depend on it. You might want to show the assumed timezone on the GUI or let users change it if needed.
Defining the API time field as date and time with timezone (not limited to UTC) prevents information loss. The Java ZonedDateTime class models this well.
However, this adds complexity, especially in the persistence layer. Your database might not support datetime with timezone in one field. You may need two fields: one for UTC time for easy sorting and another for the timezone.
Date without time = easy?
Business needs often deal with dates that don’t include a time component. For example, a subscription may be active from day X until midnight of day Y.
But don’t remove the time information from your APIs without careful thought. Timezone differences can make day Y in Europe become day Y+1 in Australia. (I enjoy celebrating the Australian New Year so I can sleep at normal hours. I know, I’m old. And I have kids.)
So, ask the business what timezone the date ranges apply to. Double-check if you need the time component with the date inputs!
Top comments (0)