0

I have a web API that can return time zone-aware time data in the form of an ISO 8601 compliant string. I have two options, return time data with an offset, and return time data converted to UTC (Zulu time).

Example, I want to return a time of 5/6/2014 5:16:00 PM Eastern Time.

Option 1: "2014-05-06T17:16:00-04:00"

Option 2: "2014-05-06T21:16:00Z"

Which is the better option? Which is the more popular option?

My customer is fine with either way. But I would like to have your opinion on which is the better option, and your reasoning behind your preference.

I think option 1 is better since it provides additional information about the time zone. In this example, assuming all parties are in the US, you know the time zone is Eastern Time based on the date and the -4:00 offset.

Zoomzoom
  • 1,042
  • 2
  • 13
  • 32
  • FYI - the reason so many are voting to close this is because you specifically asked "which is better / more popular" and called for an opinion. In the future, instead of asking "what do you think is more popular X or Y", you should try to phrase the question more empirically, such as "what are the advantages/disadvantages of X over Y". – Matt Johnson-Pint May 07 '14 at 00:43
  • Noted. Thanks for the feedback Matt! – Zoomzoom May 07 '14 at 01:44
  • By the way, I can't tell how many have voted to close this question. Where exactly is this statistic? – Zoomzoom May 07 '14 at 01:47

2 Answers2

3

This seems a bit opinion based, but from my experience it is best to always operate using UTC under the hood, and convert to local time only just before presenting time to the user.

This makes your classes know less, and less knowledge is better flexibility. In this case, the client won't have to know about server's timezone. Also it makes the code clear and easy to use, if you have an invariant that every date time variable holds UTC (except the presentation layer).

Managing time and timezones is very often source of errors that come out only in certain moments in time (like DST changes) so it can be unexpected and occur months after deployment. Best to keep these parts as simple as possible, and thoroughly tested.

BartoszKP
  • 34,786
  • 15
  • 102
  • 130
  • Thanks. Let's say I'm not responsible for the displaying of this time data to the end user. That is the job of the API consumer. Would you say it would give the consumer more information and therefore more flexibility? In .NET, if we go with option 2, then the consumer can deserialize the Zulu time string to DateTimeOffset and get UtcDateTime from it to get the UTC time, if they want. – Zoomzoom May 06 '14 at 21:46
  • 1
    @Zoomzoom Think of it as you would internationalization/localization. Internal in your app you work with a key such as "address" (if the programmers work in English). Then your app localizes that value for a French-speaking user as "adresse" for presentation in the interface. Similarly, you should generally be working with UTC date-time values in your code, storage, and database. Convert that date-time value to a time zone for presentation in the user's own time zone. As for your API, think similarly; would the API consider translation of "address" to "adresse" to be a feature or a hindrance? – Basil Bourque May 06 '14 at 22:11
  • Thanks Basil, that analogy is interesting. Although I would like to think that the time+offset format isn't localized in the sense that "adresse" is localized for French folks. Both formats are ISO 8601 compliant. The time+offset format conveys everything that Zulu string conveys, and more, does it not? This is what I'm struggling with a bit. By the way, I had a typo in my first comment. Meant to say "if we go with option 2". – Zoomzoom May 06 '14 at 22:40
  • Thanks again, Bartosz, for your input. FWIW, I up voted your answer. – Zoomzoom May 07 '14 at 01:46
  • @Zoomzoom Thanks, good luck :) Going back to your question - I agree completely with BasilBourque's response. – BartoszKP May 07 '14 at 08:15
  • Bartos, I disagree though. Both Zulu time and time + offset formats are used for the same purpose. They are exchangeable, unlike French and English. So it's not as clear cut as Basil suggests. – Zoomzoom May 07 '14 at 12:57
  • @Zoomzoom The analogy is not perfect, true, but still - less knowledge less trouble. UTC invariant in every system simplifies a lot, and makes it less prone to bugs. If you don't have an important reason to use non-UTC datetime then don't - why add unnecessary complexity? – BartoszKP May 07 '14 at 13:59
  • Thanks for your continued input Bartos. So, this "complexity" may be necessary, even though both my client and I don't need it at the moment. The fact that the time+offset format exists means there's a use case for it, which I'm not aware of. This is why I posted this question to see if anyone has had experience choosing the time+offset over Zulu. Also, I'm not completely in agreement that time+offset is more complex than Zulu. To the various datetime parsers, they have to be about the same. – Zoomzoom May 07 '14 at 17:28
  • After further thoughts, I have decided that I'll just provide a switch between the two options to my client. Best of both worlds and future proof. – Zoomzoom May 07 '14 at 19:50
  • @Zoomzoom I didn't mean parsing complexity. I meant the complexity induced by the fact, that in your code you can have datetime variables that can be either in your local time, some other local time or UTC. I know that in this case it won't be literally your code but that's my general premise for sticking to UTC. Anyway, seems that your decision is good - it probably doesn't cost you match to just return a datetime in the requested version. Good luck again :) – BartoszKP May 07 '14 at 22:19
2

It very much depends on what your API is trying to represent. Context is key

  • If all you need to represent is "the exact point in time something happened", then send back the value adjusted to UTC, with the trailing Z.

    Example: The time recorded that a user hit a particular page on your web site.

  • If you need to represent that something happened with respect to a particular local time, then send back that local time, with a trailing offset.

    Example: The time that an employee clocks in for work.

Either option are valid ISO-8601 formats, and both represent a distinct moment in time. The only difference is that the local+offset format retains the perspective of the original observer.

See also DateTime vs DateTimeOffset.

Community
  • 1
  • 1
Matt Johnson-Pint
  • 230,703
  • 74
  • 448
  • 575
  • You said " The only difference is that the local+offset format retains the perspective of the original observer." and that is exactly what my argument for option 2 is. In my case, the time data can represent either a "point in time" (timestamp) or a "time of day" (meeting time). Although in either case, the customer currently may not care about the source location's time zone. However, in the future, they may, so I think I'm sticking with the time+offset format. – Zoomzoom May 06 '14 at 22:08
  • Oops, I had a typo. Meant to say "that is exactly what my argument for option 1 is". – Zoomzoom May 06 '14 at 22:34