We are working on an API that has an authentication header in which a timestamp has to be processed. Since we might need more use of timestamps in the future and want to be consistent in what timezone we use, I'd like to know if there is a conventional timezone for APIs. UTC+0 for example.
Thanks in advance
In some cases, you will find that HTTP headers (such as the standard Date header) is in RFC5322 format (aka RFC2822, RFC822). For example: Tue, 31 Jan 2017 17:45:00 GMT
In the Date header, the time zone abbreviation is always"GMT" (which is equivalent to UTC for this purpose), even though the RFC5322 format allows for other time zones.
The above format is not really preferred, it's just something we're stuck with. You can certainly use any format you wish for your own HTTP headers though.
A much better format is the RFC3339 format. This is similar to the ISO8601 extended format. An example is: 2017-01-31T17:45:00Z. The Z at the end indicates "Zulu" time, which is the same as GMT or UTC. However, you could also specify a time zone offset from UTC, such as the equivalent local time in the US Pacific time zone: 2017-01-31T09:45:00-08:00
If you have Unix time numbers like 1485884700, the time zone is always UTC. However, this is not a good interchange format because it is not human readable, and offers no context for what epoch or precision is being used. One would have to know those things externally. It is not a good fit for HTTP headers, nor XML or JSON.
If you are talking about the body of your XML/JSON requests, then you should only be using ISO8601. There are a few other formats that people use, but they are not recommended.
With regard to what time zone you should use - that's entirely dependent on context. If you are timestamping - where you take the current time and record it, then you can indeed just work with UTC. I would think for authorization purposes, this would be reasonable. You could also work in a local time, as long as you provided the offset from UTC along with it so there is no ambiguity.
However, you said (in comments) that your data contains information about job vacancies. That sounds to me like you are talking about time in the future - and that is an exception to the "always UTC" rule. Any time you are talking about time in the future, you need to express that in terms of local time, in the most direct form you can, and you also need to provide the identifier (not the offset) of the time zone that applies.
For example, if I am talking about a job vacancy, I might say in my data:
{
"job": "dishwasher",
"available: "2017-02-13",
"start": "08:00",
"end": "16:00",
"tz": "America/New_York"
}
These values would follow the ISO8601 format for date-only and time-only (or if I wanted to combine them 2017-02-13T08:00) - and would not have a time zone specified. Instead, the IANA time zone identifier America/New_York (for US Eastern Time) is provided in a separate field.
This matters because perhaps the job continues into future months. On March 12th, the US Eastern time zone will change from UTC-5 to UTC-4. Therefore, one cannot specify a single offset, nor can you use UTC.
Also, even for a single occurrence, keep in mind that some countries continue to change their minds about what their time zone and DST rules are, which is why there are dozens of updates to the tz database every year. If you were to calculate an offset for a date and time in the future, by the time it rolls around you might find the offset had been changed by the government.
