Designing a REST API: Unix time vs ISO-8601

Published on: February 22, 2013

In what format should a REST API return and accept timestamps? The two most popular ways are Unix time (or a slight variation thereof) or ISO-8601. Both have their strengths and weaknesses and both are equally popular as we shall see. A sample of 20 APIs yielded nearly a 50/50 split. Therefore, no matter if this holds any persuasion or not, one can walk away knowing that their method of choice given Unix time or ISO-8601, is common knowledge and shouldn’t present a steep learning curve to other developers.

Unix time is completely unambiguous. It’s the number of seconds since January 1st, 1970. It’s a number and is extremely simple to convert to and from various formats. For more information, visit unix4lyfe, but in short, there are a lot of benefits to working with just a number. The nice thing about Unix time is that there is often little error checking and it is often a timestamp is stored in the database, so no conversion is necessary.

The downfall of Unix time is that it is not human readable. Until the response or request has been converted, the timestamp is essentially unintelligible. While the conversion isn’t hard for a computer, it is for a human, and we want to write an API that other humans consume. To fix this is ISO-8601. It presents the data in a well defined, human readable string format. This allows for easier development as one can curl or issue an HTTP GET request against the API and verify the timestamps.

It is in my opinion that a REST API should implement ISO-8601. The only advantages that Unix time has is that there is little conversion to and from the database. I find this advantage to be minimal at best. Conversion to and from a string in the format of yyyy-MM-dd'T'HH:mm:ssZ to an integer only adds a few cycles in the worse case. The human readability benefit of ISO-8601 cannot be measured. When I’m developing with a REST API and I start crafting my queries, I write them by hand and the time alone from not worrying about converting timestamps into Unix time is probably more than the time saved if I had used Unix time.

Data from sampled REST APIs:

Note: flattr was the only API that had both Unix time and ISO-8601 in the response. Unix time was denoted by appending “_in_seconds” to the field.

If you'd like to leave a comment, please email hi@nickb.dev

2017-10-04 - Jason Harmon

I completely agree that ISO-8601 is a clear winner here for developer experience. Unix timestamp requires machine interpretation, which makes humans developing and debugging on the given API hurt inside. I wrote a big post on the topics of timezones in APIs, which turned into a near compendium on the subject. http://apiux.com/2013/09/11/api-timezones/

I love that you did a survey of this nature…I think it would be interesting to try and gauge the relative age of these systems, to see if we’re trending toward ISO-8601 or toward timestamps. Let’s hope it’s the former :)

2017-10-04 - David

Hi

Just to let you know, Unix time may not be completely unambiguous. In fact it does not handle leap seconds well, and I believe in some cases it can go backwards, which may have undesirable effects in a number of technical applications. Therefore I would strengthen your conclusion of using ISO-8601 (in my view ideally UTC)