REST API response standards: Timezone

Question

Is there any ISO standard for how we should return a timezone in a REST API?

If I return a TimeZone type from a ASP.NET WebApi 2 action, the framework serialises the response model to look like this:

{
    "Id": "Dateline Standard Time",
    "DisplayName": "(UTC-12:00) International Date Line West",
    "StandardName": "Dateline Standard Time",
    "DaylightName": "Dateline Daylight Time",
    "BaseUtcOffset": "-12:00:00",
    "AdjustmentRules": null,
    "SupportsDaylightSavingTime": false
}

Not that i know of. But a timezone isn't really an entity, it's more like an object defined by a timezone offset, a name (which can be internationalized or not) and maybe other attributes of interest. I would tailor what the API returns based on what the minimum requirement for the use case(s) would be. From my experience to adhere to time-keeping standards that go beyond UTC or Unix time only increases effort and makes the outcome more prone to problems. — Sandman, May 18 '15 at 16:27

score 2 · Accepted Answer · edited May 23 '17 at 12:14

Microsoft time zones, such as the ones used by the TimeZoneInfo object, can indeed be serialized and deserialized, using the FromSerializedString and ToSerializedString methods. They can also be referenced with their Id property. Both of these are on the TimeZoneInfo class, not the TimeZone class (which you should not be using at all).

However, if you send either a Microsoft time zone ID or the serialized form of the time zone, your API will only be easily consumable by other .NET applications. You will have a really difficult time using Microsoft time zones outside of .NET.

There is no official standard for time zones, but the closest thing would be the identifiers provided by the IANA time zone database. For example, to convey the US Eastern time zone, you would pass "America/New_York" in your API. You can read more about these in the timezone tag wiki, and also on Wikipedia. The nice thing about IANA time zones, is that it is implemented on every platform - so while it's not a standard, it is much more portable than the Microsoft time zones that only work on Windows.

For .NET, the best way I know of to work with IANA time zones is through the Noda Time library. For example:

DateTimeZone tz = DateTimeZoneProviders.Tzdb["Asia/Tokyo"];

You can read more in the Noda Time user guide.

If you've already built your system around TimeZoneInfo, consider that you may still wish to translate to IANA time zones in your API layer. You can read about how to do that in this answer.

score 0 · Answer 2 · answered May 18 '15 at 15:36

0

The most common ISO standard I've seen used for REST API's, especially ones designed with interop in mind, is the ISO 8601 standard.

http://en.wikipedia.org/wiki/ISO_8601

answered May 18 '15 at 15:36

Karen B

331
2
9

1

But there is no specification for timezones that I can see? – Dave New May 18 '15 at 15:38
As a general practice, the API should use UTC dates/time and let the client code convert to timezones. – Karen B May 18 '15 at 17:02
Absolutely. But in this situation the intention is for the consumer to understand which timezone a country-specific resource resides in. For example, we have an endpoint to receive more information on organisations (the resource). An important aspect to be returned is the timezone in which the organisation operates. This doesn't have to do with dates and times. It's purely informative data. – Dave New May 18 '15 at 18:34

REST API response standards: Timezone

2 Answers2