Search code examples
apidatetimetimestampunix-timestamp

Why most API use ISO-8601 timestamp format over epoch?

I've seen a lot of projects where epoch format was used to represent dates. But as far as I know most of developers use ISO-8601 format for timestamp. I wonder what benefits ISO-8601 has over epoch?

I found this question on SO, but it's more about proper date formatting in general. I know epoch timestamps often used to represent last update or creation time - but I think it's rather about databases. For me epoch timestamp is a little confusing, at least because different languages utilize different time units (i.g. it's seconds in PHP, but milliseconds in Java, Javascript, etc.) while ISO-8601 format is standard.

Solution

  • tl;dr

    Which value you would rather see when debugging a critical problem at 3 AM?

    • 1668329462529
    • 2022-11-13T08:51:02.529Z

    Use ISO 8601 text for clarity

    Regarding the tracking of time using an elapsed count from some epoch reference, two issues to consider:

    • Various granularities are used by various protocols such as whole seconds, milliseconds, microseconds, hundreds of microseconds, nanoseconds, etc.
    • Various epoch references are used by various systems/protocols.

    So encountering a mere number that is supposed to represent a date-time can be ambiguous. Such numbers are often error-prone because of incorrect assumptions or miscommunications.

    A mere number cannot be parsed as a moment by a human mind. A timestamp such as 15687402956 or 1668329058 is unreadable to mere mortals. So debugging is made difficult. And invalid values may go unnoticed.

    Generally better to store and exchange date-time values as text in standard ISO 8601 format. This standard defines formats that are thoughtfully designed to be relatively clear and unambiguous across human cultures and languages.

    Offset of zero

    And it is generally best to report moments (specific points on the timeline) with an offset-from-UTC of zero hours-minutes-seconds unless you have a specific reason to use offsets.

    For example, in Java:

    Instant instant = Instant.now() ;
String output = instant.toString() ;  // Generates text in ISO 8601 format.

    See this code run at Ideone.com.

    2022-11-13T08:17:31.634762Z

    The Z at the end of an ISO 8601 string means an offset of zero, and is pronounced “Zulu”.

    Going the other direction:

    Instant instant = Instant.parse( "2022-11-13T08:17:31.634762Z" ) ;

    ZonedDateTimes

    Note that one shortcoming of ISO 8601 is the omission of time zones. The standard covers only offsets.

    The java.time.ZonedDateTime class in Java wisely extends the ISO 8601 standard to append the time zone name in brackets when generating text. One of the biggest advantages of ZonedDateTime over an OffsetDateTime is that it adjusts the time zone offset automatically (e.g. in the case of DST or when a country changes its time zone offset).

    ZoneId z = ZoneId.of( "Asia/Tokyo" ) ;
ZonedDateTime now = ZonedDateTime.now( z ) ;
String output = now.toString() ;  // ISO 8601 format extended to append the name of the zone in brackets.

    When run in Ideone.com. Note the formal time zone name (Continent/Region) at the end.

    2022-11-13T17:26:08.717876+09:00[Asia/Tokyo]

    Hopefully, this representation of time zones will catch on as a de facto standard, and someday be added to the official standard.

    Definitions

    A quick review of offset & time zone:

    • An offset is merely a number of hours-minutes-seconds ahead or behind the temporal prime meridian of UTC.
    • A time zone is a named history of the past, present, and future changes to the offset used by the people of a particular region, as decided by their politicians.

    When to use count

    The only place I would use a count as a way of tracking time would be where resources are extremely constrained. A count of milliseconds takes only 32-bits.

    In commonplace business app programming, such a need has largely evaporated. Memory is cheap, storage is cheap.

    In contrast, debugging is expensive, and business miscommunication is expensive. So use ISO 8601 text wherever practicable.