markdown guide

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.


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.


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


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.


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


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 :)


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.


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.


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

Classic DEV Post from Mar 2

What is the importance of committing mistakes?

It is a well-known fact that all human beings are different and unique in their ways. However, no matter how unique and different we are from one another, one thing which remains the same between all of us is our innate nature to commit mistakes.

Xing Wang profile image
Bachelor's and Master's in CS from MIT. Previously, worked @ Microsoft & Zynga. Currently Co-Founder of Moesif (, the most advanced API analytics platform.

DEV is a community of software developers

Sign up (for free)