DEV Community

Do you prefer unix epoch (a number) or ISO 8601 (a string) for timestamps?

Xing Wang on March 19, 2019

In interfaces such as APIs such as REST or Graphql, most JSON doesn't support time stamp data type natively, you'll have to use one or the other. Or what alternatives do you prefer to use?

Collapse
 
ben profile image
Ben Halpern

I sort of feel like we're wrong either way. Even epoch is kind of frustrating because of how it's either given as seconds or milliseconds as a default depending on the environment and there's always an overhead of making sure you're doing it right.

An API that delivered the value in a couple ways and was super explicit about it seems like something that's good to work with—even if the client could translate between them.

Collapse
 
xngwng profile image
Xing Wang

yeah, the problem is that there is no standard way.

Stripe APIs use epoch.
Twitter and Dropbox APIs use ISO 8601.

So just curious what about people's preferences.

Collapse
 
rhymes profile image
rhymes

I wouldn't be surprised if Stripe chose unix epochs because they interact with third party bank or credit card systems and that makes their lives easier or because they store payment events in a time series DB and their DB uses unix timestamps. Maybe after validating the payload, they ship it to some queue and that gets written as is to a DB.

Or maybe they just chose by tossing a coin :D

Collapse
 
nektro profile image
Meghan (she/her) • Edited

In reality I always use a string. And always in the format YYYY-MM-DD with the optional addition of hh:mm:ss. This means a full date-time is only 19 bytes instead of 32 or 64 since 95% of the time I don't need the millisecond accuracy of epoch time.

Collapse
 
tobiassn profile image
Tobias SN

Actually iirc, Unix time is 64 bits, not bytes. That means it’s only 8 bytes.

Collapse
 
nektro profile image
Meghan (she/her)

Yep. My mistake.

Collapse
 
rhymes profile image
rhymes

I've seen Unix timestamps used in APIs but I've always used ISO UTC datetimes because I like they are readable both by humans and machines easily.

Think about the various transformations inwards and outwards. An API will likely accept time as a string in input (especially if you need to know the timezone of the caller), the language with which the app is built in will likely easily parse both formats (and since you're a human you'll use operators to manipulate time that deal with something more "chatty" than just seconds since epoch). If the app is backed by a relational DB that date you parsed in input will probably land in a "datetime with timezone" column or something like that. So you have strings and datetime types all the way in input.

You're left with a decision of how to present the output, if there's not much difference in performance I'd either use the ISO string or... both :)

Collapse
 
weakish profile image
Jang Rush

timestap0 = 2016-12-31T23:59:59Z
timestap1 = 2016-12-31T23:59:60Z
timestap0.epoch == timestap1.epoch

That is why I prefer ISO 8601, more accurate and more human-readable.
And I do not think under the context of REST or GraphQL, a few extra bytes unix epoch saves will make any difference.

Collapse
 
jpilkahn profile image
Johannes Pilkahn • Edited

That's an entirely misconstrued perception there, Jang.

Whether you choose to express that second as a UNIX or ISO 8601 timestamp - it is not the same second.

timestap0.epoch == timestap1.epoch is just blatantly wrong.
Not even remotely opinion-territory.
Just wrong.

2016-12-31T23:59:59Z = 1483228799
2016-12-31T23:59:60Z = 1483228800
1483228799 != 1483228800

What's your platform? NT?

Collapse
 
weakish profile image
Jang Rush

pubs.opengroup.org/onlinepubs/9699... leap seconds are ignored in unix epoch.

Different implementations may or may not conform to this standard.

Collapse
 
joaopms profile image
João

Under the hood, it doesn't really matter. ISO 8601 is easier for humans to read but unix epoch takes less bytes on the API response. Other than that, I guess it only depends on your preference.

Collapse
 
thejoezack profile image
Joe Zack

Another vote for 8601, since I can actually read it. :)