CODEWITHSUNDEEP
javarestdateurlodata
MoneerOmar
MoneerOmar

Reputation: 225

accepted way to send date and time with timezone parameter in URL

In OData/REST service I want to allow date parameters startDate and endDate that marks the daterange of data returned. Example: 

GET /events?startDate=XXX&endDate=YYY

Questions:

  1. What are the standard formats for date and time in URL?
  2. Should I consider adding a timezone (or UTC offset)? What is expected if timezone was not added?

Upvotes: 8

Views: 16938

Answers (2)

user7605325
user7605325

Reputation:

The W3C date format linked in @user7294900's answer is a good option. You just need to take care about the characters : and + - it's recommended to URL-encode those characters: in this case, a date like 2017-08-07T12:09:23.555+01:00 would become 2017-08-07T12%3A09%3A23.555%2B01%3A00 in the URL.

You can also use ISO 8601 formats, which allows a format without the - and : separators, so a date like 2017-08-07T12:09:23.555+01:00 could also be written as 20170807T120923.555+0100 (you'll still have characters to URL-encode, but this can become more readable than the first option: 20170807T120923.555%2B0100)

W3C date format is a profile (or a subset) of ISO 8601, so both are good choices as most modern languages and systems have support for ISO formats.

How/Should I consider adding a timezone (or UTC offset)?

First of all, timezone and offset are not the same thing (although they're related to each other).

Offset is the difference from UTC: +02:00 means "2 hours ahead of UTC" and -02:00 means "2 hours behind UTC".

Timezone is a set of all different offsets that a region had, has, and will have during its history, including the exact date and time when those changes occur.

If I just have a date like 2017-08-07T12:09:23.555+01:00, the offset +01:00 just indicates that it's 1 hour ahead of UTC, but it doesn't say in which timezone it is. It can be London during Daylight Saving Time (DST, or summer time), or it can be Andorra during winter, or many others.

Java uses IANA timezones names (always in the format Region/City, like America/New_York or Europe/Berlin). Avoid using the 3-letter abbreviations (like EST or PST) because they are ambiguous and not standard.

If your application will deal with dates and times at different zones, I recommend working internally with UTC (so dates will be like 2017-08-07T12:09:23.555Z - the Z means "zero offset", which in turn is the same as "UTC"). So your backend code always works with UTC and just changes it to another timezone when needed (like when displaying to a user).

If you don't need to work with different timezones or don't need to know the exact instant of events, you can work with a "local date" (without timezone nor offset). It'll depend on your requirements.

What is expected if the timezone is not added?

If you work with local date/time (without timezone/offset), you can have "strange" or unexpected results, depending on how your code deals with the dates.

Suppose I have the date/time 2017-08-07T22:00 (August 7th 2017, at 10 PM). It doesn't have any timezone information, so you must assume in which region of the world this date is: you can assume it's in your timezone, or in whatever timezone the system is using, but these calculations will fail if you start involving another timezone.

Example: if I consider this date to be in London, it'll be equivalent to 9 PM UTC. But if this local date is in Los Angeles, it'll be equivalent to 2017-08-08T05:00 in UTC (10 PM in Los Angeles equals the next day at 5 AM in UTC). This date/time will represent a different instant depending on the timezone used.

So, if the offset is not used, you may have those results, but of course, this depends on what your code is doing with the dates. If you're treating it as a local date and time, there should be no problem. If you're doing calculations considering UTC and/or different time zones, there might be problems.

Upvotes: 25

Ori Marko
Ori Marko

Reputation: 58822

See World Wide Web Consortium (W3C) date formats, you can send in format YYYY-MM-DDThh:mm:ss.sTZD

e.g 1997-07-16T19:20:30.45+01:00

Without seconds:

YYYY-MM-DDThh:mmTZD (eg 1997-07-16T19:20+01:00)

  1. Default time zone is US Eastern Standard Time:

1994-11-05T08:15:30-05:00 corresponds to November 5, 1994, 8:15:30 am, US Eastern Standard Time.

1994-11-05T13:15:30Z corresponds to the same instant.

Upvotes: 1

Related Questions