12

Whilst implementing our API, the issue of datetime and timezones came up.

All dates are normalized to UTC in the database. Currently, in the non-API application, all datetimes are converted based on users preferences first before presented.

Now the same question came up for the API: should the the API be able to return the datetime appropriate for a timezone based on request semantics?

E.g. GET /posts?timezone=America/Sao_Paulo ?

Or should it still be done on whatever client is accessing the API?

Update: since it came up a few times: currently timestamps with timezone are returned (although it's always TZ offset +00:00). The format is the popular 8601: 2015-10-29T23:00:49+00:00

mark
  • 229
  • 1
  • 2
  • 5
  • If you return a timestamp containing a timezone, the client can easily convert it to whatever local time necessary. Anyway, this question doesn't seem to be REST-related at all. There are numerous ways you can implement this that don't violate the principles of REST. Please mind that exposing this parameter means more work for you. In a truly RESTful architecture, you'll need to make these links discoverable somehow. It strikes me as needlessly complicated thing to implement both on client and server side. – toniedzwiedz Nov 01 '15 at 11:36
  • > It strikes me as needlessly complicated thing to implement both on client and server side. Thanks for the input! – mark Nov 01 '15 at 12:38

4 Answers4

18

You should return an absolute point in time, then anyone can localize that timestamp as needed. By "absolute timestamp" I mean either a UNIX timestamp or a human readable timestamp which includes the timezone in one of the standardized ISO formats, e.g. "2007-04-05T14:30Z". This can trivially be converted to a local timezone by the client as necessary.

If you want to accept a timezone parameter and localize the timestamp to that timezone that's fine, but you should still use the absolute timestamp incl. timezone in your response, e.g. "2007-04-05T16:30-02:00". Given that this value is identical to the previous non-localized one, it's pretty questionable why you'd go through the trouble of offering this parameter. The exact display format of the timestamp is ultimately up to the frontend of the client, so it'll likely post-process the value anyway.

deceze
  • 2,215
  • 1
  • 19
  • 19
  • 4
    "it's pretty questionable why'd you'd go through the trouble" -- if nothing else, it's the thin end of the wedge. The next client of this API might ask you to let them specify a `strftime` format (plus locale, for month/day names) for the same reasons of convenience that the first client found it useful to specify a timezone. Even with timezone as the only concession, you've made your API's response more complex: it's no longer just "a timestamp in the same format every time", it's "a timestamp expressed in the way I was asked to express it" – Steve Jessop Oct 31 '15 at 12:41
  • 4
    Exactly, complexity. Complexity is evil. It makes everybody work harder without any added value to the product or business. Death by a thousand paper cuts. – Brandon Oct 31 '15 at 13:14
  • 2
    >You should return an absolute point in time I clarified my question that I'm doing this already. Thanks for your insight! – mark Nov 01 '15 at 12:39
4

If you already have the logic to convert datetime values to the local timezone of the user, you could offer both possibilities in your API.

If a client makes a request like GET /posts, then they get all times in the default timezone (UTC).
If a client makes a request like GET /posts?timezone=America/Sao_Paul, then all times in the reply would be adjusted to the specified timezone.

It is then up to the client implementation what they want to do with timezones.

Bart van Ingen Schenau
  • 71,712
  • 20
  • 110
  • 179
2

Usualy you would expect UTC from an API.

However, if your 'REST API' is just the server side part of a webpage using a javascript framework. I would argue that in fact you are returning a ViewModel and so it should contain localized strings, numbers and times.

Ewan
  • 70,664
  • 5
  • 76
  • 161
2

It's a bad, bad, bad idea. Consider a situation where the client stores responses from the server, and then the user travels to a different time zone. Now you have a situation where this "feature" will at best give you no advantage whatsoever, or create enormous trouble.

BTW. For how many timezones and how many clients are you going to test this? If the server gives the expected reply for America/Sao_Paul, what will it respond for America/Sao_Paulo?

gnasher729
  • 42,090
  • 4
  • 59
  • 119
  • That was a mistake on my part, I corrected it to `America/Sao_Paulo`. I guess it's up for discussion what happens if the timezone cannot be identified; either because it's plain wrong or the TZ database is out of date (I find the latter unlikely for the actual names [but not so for offset values). However, in either case, I would probably return a `400 BAD_REQUEST` response. – mark Nov 02 '15 at 07:45