7 ms·

Designing a REST API: Unix Time vs. ISO-8601 (2013)

42 points by ducaale 5y ago

softwarebeware 5y ago
I’m quite surprised that Unix time is so common. My anecdotal experience with dozens of public and internal APIs over 20 years of development is that the most common format is local time followed by ISO. I actually have almost never seen Unix time.
- jaywalk 5y ago
  Local time? In a public API?
  - softwarebeware 5y ago
    Programmers are lazy. I've seen more than my fair share of the default behavior of a language like Java implemented. Which usually means just making a system call for the current time and will return the time in whatever time zone the system happens to be set for.
- hnbad 5y ago
  If I had a penny for every time I assume an API takes Unix time in milliseconds or seconds and it turns out to be the other...
arjvik 5y ago
Unix Time should be an implementation detail. ISO-8601 is IMO the preferred format for APIs.
koeng 5y ago
Unix time is not unambiguous. It is linked to UTC, so occasionally there are leap seconds, and there isn’t a standard format for these (two seconds == one second, or skip a second)[1]. TAI is a better format, but turns out the common TAI libraries just code the TAI offset from Unix time. [1] https://geometrian.com/programming/reference/timestds/index.php https://geometrian.com/programming/reference/timestds/index....
- thehappypm 5y ago
  How does that make sense? Unix time is basically a stopwatch that someone started a long time ago. How would a leap second matter?
  - koeng 5y ago
    Because unix time isn't a stopwatch that someone started a long time ago. Leap seconds change unix time because unix time is tied to UTC.
    - erdos4d 5y ago
      I'm not really following. How does the fact that Unix timestamps are in terms of UTC affect whether leap seconds get incorporated into the timestamp or not? Do leap seconds work differently in UTC or something?
      - growse 5y ago
        Unix timestamp assumes there are exactly 86400 seconds in a day. Or, in other words, if your timestamp is a multiple of 86400, it's midnight UTC. There are not alway 86400s in 1 day. Midnight is not a whole number of multiples of 86400 after Jan 1st 1970.
        deleted 5y ago
        [deleted]
        fivea 5y ago
        > There are not alway 86400s in 1 day. Midnight is not a whole number of multiples of 86400 after Jan 1st 1970. Isn't that an issue with the format you want to convert UNIX time to ? I mean, UNIX time is quite clearly and unambiguously defined as the number of seconds that passed since January 1st 1970. How are UTC's leap seconds any relevant?
        5y ago
stickfigure 5y ago
JSON needs to have a timestamp type. Parsers should automatically convert them to/from native language timestamp objects. Human readable is preferred, but really the critical aspect is to make the JSON self-describing. If timestamps are self-describing, any smart editor can display them properly.
- jaywalk 5y ago
  .NET has no trouble going between ISO-8601 and the native DateTime type.
  - stickfigure 5y ago
    If you have a priori knowledge of the schema (say, mapping to/from classes) you can convert anything. You don't even need something like JSON, you could just have a binary format and IDL. JSON self-describes booleans, numbers, strings, arrays, objects, and null. This is especially convenient when working with dynamic or ambiguous structures, and working in dynamically typed languages. Timestamp is sufficiently common and useful that it should be added to that list. If you mean ".NET parser pattern matches strings and converts them dynamically" - that's the same horrible behavior yaml parsers have and it causes endless trouble. Imagine parsing titles of posts and some clever author makes a title that matches the timestamp format.
    - jaywalk 5y ago
      The .NET parser will only parse ISO-8601 to a DateTime if that's the type you tell it to accept. If you tell it to accept a string, it won't try to do anything funny no matter what that string may look like.
  - dmitriid 5y ago
    When .Net just started, they would deserialzie datetime to... a string which looked something like `DateTime\(2007-12-10\)`. 10-15 years later I'm still baffled by that early decision (and glad it's been fixed since then)
- 5y ago
divbzero 5y ago
> A sample of 20 APIs yielded nearly a 50/50 split. Is it still a 50/50 split today? I suspect ISO 8601 has grown to become the standard.
- deleted 5y ago
  [deleted]
- hnbad 5y ago
  Public APIs maybe. Internal? I'm not so sure. Since JSON doesn't have a time type, an ISO date field always requires validation and there are plenty of edge cases to consider (e.g. do you want to accept bare/naive datetimes, do you want to require all parts to be present, do you allow week dates, etc). The biggest advantage of ISO 8601 is probably that you can also use it to represent dates and/or times rather than only datetimes but this can result in unnecessary ambiguity (e.g. if you decide to split the datetime into a date and a time field and make assumptions about the timezone).
deathanatos 5y ago
There's also RFC 3339[1] which is, IMO, a bit better. The RFC is readily readable, unlike an ISO standard, and the RFC is — mostly — more restrictive. ISO is fun up until you have to parse "2022-089". Yes, that's a valid ISO date. And it's in March. (And yes, I've seen that used in the wild, though I don't know why anyone would ever choose that format.) [1]: https://datatracker.ietf.org/doc/html/rfc3339 https://datatracker.ietf.org/doc/html/rfc3339
csours 5y ago
> "Unix time is completely unambiguous." Looks like someone hasn't had to deal with data from multiple different time zones processed by code written by different developers over several years! Unix time could be unambiguous, but it is not in practice. If it has been unambiguous for you, congratulations! Use ISO style dates if you don't want to spend the rest of your life explaining what a date actually means.
- ackfoobar 5y ago
  > data from multiple different time zones processed by code written by different developers over several years! This feels strongly an argument FOR unix timestamps. Simply a number, the biggest mess up is seconds/millis. This order of magnitude difference is not that hard to disambiguate.
  - csours 5y ago
    Unix timestamps have a convention of being an offset from Jan 1 1970 00:00. But is that Jan 1 1970 GMT or UTC or local time? There is a right answer here! But! Did all the developers do the right thing? Was the default implementation correct? --- What I'm saying is - in your json document, you see a number and you rely on a convention to decode that number. The number has no way to tell you anything about what the number actually means. The ISO standard does. People could still mess it up, but I feel like the people who use the ISO standard care a lot more than the people who use the Unix standard.
    - ackfoobar 5y ago
      > Did all the developers do the right thing? "The right thing" is, for example, simply `System.currentTimeMillis()` in Java. I don't have to think about what 0 means. All I need to know is there's a mapping from an instant to a number. This representation is arguably closer to the essense of time. Barring relativistic effects, it's just an affine line. Dates and timezones are artificial structure that we put on this line.

42 points by ducaale 5y ago

I’m quite surprised that Unix time is so common. My anecdotal experience with dozens of public and internal APIs over 20 years of development is that the most common format is local time followed by ISO. I actually have almost never seen Unix time.

jaywalk 5y ago
Local time? In a public API?
- softwarebeware 5y ago
  Programmers are lazy. I've seen more than my fair share of the default behavior of a language like Java implemented. Which usually means just making a system call for the current time and will return the time in whatever time zone the system happens to be set for.
hnbad 5y ago
If I had a penny for every time I assume an API takes Unix time in milliseconds or seconds and it turns out to be the other...

arjvik 5y ago

Unix Time should be an implementation detail. ISO-8601 is IMO the preferred format for APIs.

koeng 5y ago

Unix time is not unambiguous. It is linked to UTC, so occasionally there are leap seconds, and there isn’t a standard format for these (two seconds == one second, or skip a second)[1]. TAI is a better format, but turns out the common TAI libraries just code the TAI offset from Unix time. [1] https://geometrian.com/programming/reference/timestds/index.php https://geometrian.com/programming/reference/timestds/index....

thehappypm 5y ago
How does that make sense? Unix time is basically a stopwatch that someone started a long time ago. How would a leap second matter?
- koeng 5y ago
  Because unix time isn't a stopwatch that someone started a long time ago. Leap seconds change unix time because unix time is tied to UTC.
  - erdos4d 5y ago
    I'm not really following. How does the fact that Unix timestamps are in terms of UTC affect whether leap seconds get incorporated into the timestamp or not? Do leap seconds work differently in UTC or something?
    - growse 5y ago
      Unix timestamp assumes there are exactly 86400 seconds in a day. Or, in other words, if your timestamp is a multiple of 86400, it's midnight UTC. There are not alway 86400s in 1 day. Midnight is not a whole number of multiples of 86400 after Jan 1st 1970.
      - deleted 5y ago
        [deleted]
      - fivea 5y ago
        > There are not alway 86400s in 1 day. Midnight is not a whole number of multiples of 86400 after Jan 1st 1970. Isn't that an issue with the format you want to convert UNIX time to ? I mean, UNIX time is quite clearly and unambiguously defined as the number of seconds that passed since January 1st 1970. How are UTC's leap seconds any relevant?
        5y ago

stickfigure 5y ago

JSON needs to have a timestamp type. Parsers should automatically convert them to/from native language timestamp objects. Human readable is preferred, but really the critical aspect is to make the JSON self-describing. If timestamps are self-describing, any smart editor can display them properly.

jaywalk 5y ago
.NET has no trouble going between ISO-8601 and the native DateTime type.
- stickfigure 5y ago
  If you have a priori knowledge of the schema (say, mapping to/from classes) you can convert anything. You don't even need something like JSON, you could just have a binary format and IDL. JSON self-describes booleans, numbers, strings, arrays, objects, and null. This is especially convenient when working with dynamic or ambiguous structures, and working in dynamically typed languages. Timestamp is sufficiently common and useful that it should be added to that list. If you mean ".NET parser pattern matches strings and converts them dynamically" - that's the same horrible behavior yaml parsers have and it causes endless trouble. Imagine parsing titles of posts and some clever author makes a title that matches the timestamp format.
  - jaywalk 5y ago
    The .NET parser will only parse ISO-8601 to a DateTime if that's the type you tell it to accept. If you tell it to accept a string, it won't try to do anything funny no matter what that string may look like.
- dmitriid 5y ago
  When .Net just started, they would deserialzie datetime to... a string which looked something like `DateTime\(2007-12-10\)`. 10-15 years later I'm still baffled by that early decision (and glad it's been fixed since then)
5y ago

divbzero 5y ago

> A sample of 20 APIs yielded nearly a 50/50 split. Is it still a 50/50 split today? I suspect ISO 8601 has grown to become the standard.

deleted 5y ago
[deleted]
hnbad 5y ago
Public APIs maybe. Internal? I'm not so sure. Since JSON doesn't have a time type, an ISO date field always requires validation and there are plenty of edge cases to consider (e.g. do you want to accept bare/naive datetimes, do you want to require all parts to be present, do you allow week dates, etc). The biggest advantage of ISO 8601 is probably that you can also use it to represent dates and/or times rather than only datetimes but this can result in unnecessary ambiguity (e.g. if you decide to split the datetime into a date and a time field and make assumptions about the timezone).

deathanatos 5y ago

There's also RFC 3339[1] which is, IMO, a bit better. The RFC is readily readable, unlike an ISO standard, and the RFC is — mostly — more restrictive. ISO is fun up until you have to parse "2022-089". Yes, that's a valid ISO date. And it's in March. (And yes, I've seen that used in the wild, though I don't know why anyone would ever choose that format.) [1]: https://datatracker.ietf.org/doc/html/rfc3339 https://datatracker.ietf.org/doc/html/rfc3339

csours 5y ago

> "Unix time is completely unambiguous." Looks like someone hasn't had to deal with data from multiple different time zones processed by code written by different developers over several years! Unix time could be unambiguous, but it is not in practice. If it has been unambiguous for you, congratulations! Use ISO style dates if you don't want to spend the rest of your life explaining what a date actually means.

ackfoobar 5y ago
> data from multiple different time zones processed by code written by different developers over several years! This feels strongly an argument FOR unix timestamps. Simply a number, the biggest mess up is seconds/millis. This order of magnitude difference is not that hard to disambiguate.
- csours 5y ago
  Unix timestamps have a convention of being an offset from Jan 1 1970 00:00. But is that Jan 1 1970 GMT or UTC or local time? There is a right answer here! But! Did all the developers do the right thing? Was the default implementation correct? --- What I'm saying is - in your json document, you see a number and you rely on a convention to decode that number. The number has no way to tell you anything about what the number actually means. The ISO standard does. People could still mess it up, but I feel like the people who use the ISO standard care a lot more than the people who use the Unix standard.
  - ackfoobar 5y ago
    > Did all the developers do the right thing? "The right thing" is, for example, simply `System.currentTimeMillis()` in Java. I don't have to think about what 0 means. All I need to know is there's a mapping from an instant to a number. This representation is arguably closer to the essense of time. Barring relativistic effects, it's just an affine line. Dates and timezones are artificial structure that we put on this line.