18

For passing times in JSON to/from a web API, why would I choose to use an ISO8601 string instead of simply the UTC epoch value? For example, both of these are the same:

Epoch = 1511324473
iso8601 =   2017-11-22T04:21:13Z

The epoch value is obviously shorter in length, which is always good for mobile data usage, and it's pretty simple to convert between epoch values and the language's local Date type variable.

I'm just not seeing the benefit to using an ISO string value.

Gargoyle
  • 9,590
  • 16
  • 80
  • 145

2 Answers2

18

Both are unambiguous and easy to parse in programs. The benefit of epoch like you have mentioned is that it is smaller and will be faster to process in your program. The downside is it means nothing to humans.

iso8901 dates are easy to read on their own and don't require the user to translate a number in to a recognizable date. The size increase in iso8601 is unnoticeable when compared to much much larger things like images.

Personally I would pick ease of reading over speed for an API as it will cut down on debugging time while inspecting values sent and received. In another situation such as passing times around internally you may wish to choose the speed of an integer over text so it depends which you think will be more useful.

Qwertie
  • 5,784
  • 12
  • 45
  • 89
12

Unix/Epoch Time
+ Compact

+ Easy to do arithmetic actions without any libraries, i.e. var tomorrow=now()+60*60*24

- Not human-readable

- Cannot represent dates before 1 January 1970

- Cannot represent dates after 19 January 2038 (if using Int32)

- Timezone and offset are "external" info, there is ambiguity if the value is UTC or any other offset.

- Officially the spec supports only seconds.

- When someone changes the value to milliseconds for better resolution, there is an ambiguity if the value is seconds or milliseconds.

- Older than ISO 8601 format

- Represents seconds since 1970 (as opposed to instant in time)

- Precision of seconds

ISO 8601 Time
+ Human readable

+ Represents instant in time, as opposed to seconds since 1970

+ Newer then Unix time format

+ Specifies representation of date, time, date-time, duration and interval!

+ Supports an offset representation

+ Precision of nanoseconds

- Less compact

- For any arithmetic actions, reach library is required (like java.time.OffsetDatetime)

beta
  • 2,380
  • 21
  • 38
Igal
  • 1,084
  • 2
  • 13
  • 33
  • 3
    There is **zero ambiguity** with seconds since the epoch, as the epoch began 0:00:00 01-01-1970 **UTC, as per definition.** If you "convert" a timestamp with a timezone offset, that's a user error. It ain't the time keeping system's fault, it it's misused. Also, one **can express times well before 1970** - the minimum representable date is Friday 1901-12-13 (`1970 + INT32_MIN`). Integers are *signed*, you might remember... – Johannes Pille Jun 01 '20 at 20:26
  • Timezone being "external" is a positive because Unix time will be same across all timezones. – mismaah Jun 16 '21 at 06:45
  • 1
    @JohannesPille ambiguity can creep in e.g. if an API expects milliseconds since the epoch (instead of seconds). In that case, when a client mistakenly provides time in seconds and the service interprets it as milliseconds, there has been a major miscommunication. The worst part, though, is that the miscommunication was not obvious to either party because it was likely interpreted as a valid representation of a time. – Ben Coppock Sep 23 '21 at 19:49
  • You've stated a negative of epoch is "Represents seconds since 1970 (as opposed to instant in time)". Doesn't an ISO date also represent a time since another time (i.e. 2000 years after Christ)? All representations of time are relative, there is no "instance" in time without comparing it to another time. – JMadelaine Aug 13 '23 at 08:42