APIs and dates

Time for a rant. If you are building an API, whether it is for public consumption or not, you should make sure you communicate dates in an unambiguous way.

You should always be able to figure out the exact time, regardless of time zone or daylight saving. The best way is to just use UTC. Or, if you can’t/won’t do that, you should include the time zone every time you mention a date. If you don’t, then you’re going to run into trouble when daylight saving ends, because you end up with the hour that precedes the changeover, and the hour that follows it, being the same. And that causes problems.

You should also not rely on date offsets from the current date, because your clients cannot be guaranteed to have an accurate time. So if you have an offset of 0 in your data that means “today” but your clients’ clocks are off, then they might think the data belongs as part of yesterday. Or tomorrow. And that is annoying.

Offsets from a particular point in time are fine though. And I don’t mind what epoch/reference date you choose. As long as it’s consistent.

APIs, in my opinion, are meant for computer-to-computer communication. They shouldn’t handle prettifying dates, for example. So you should pick the right tool for the job.

That is all.