Our front end wants only a date. My understanding is that the industry standard for JSON.NET and Web Api is ISO 8601. Is is possible to return a date portion ONLY from our Web Api while adhering to ISO 8601 standards, or will the date property (dateOfBirth) of our JSON object have to have all zeroes for the time portion in order to adhere to the ISO 8601 standard?
ISO 8601 is a standard that specifies many different formats. Section 4.1.2 covers dates, section 4.2.2 covers time of day, and section 4.3 covers date and time of day combined. The spec also defined a "basic format" and an "extended format" for each.
Some examples in the basic format:
Date: 20190611
Local time: 140000
Date and local time: 20190611T140000
Some examples in the extended format:
Date: 2019-06-11
Local time: 14:00:00
Date and local time: 2019-06-11T14:00:00
Also there are variations to the time of day which add Z for UTC or a specific offset from UTC such as -07:00. (These do not apply to the date-only form.)
Thus, to answer your question directly, yes you can pass just the date. That is still ISO 8601 compliant, as long as you use either of the date-only forms shown above. (The extended form is usually chosen for JSON responses.)
By the way, this isn't just an option, it's a best practice. Date-only value such as birth dates and other anniversary dates should not have a time attached - even if it's all zeros. Doing so contorts their meaning.
That said, be aware of some pitfalls:
Some platforms do not have a built-in date-only data type, and will assign midnight.
JavaScript's Date object (via the ECMAScript standard) deviates from ISO 8601 and parses date-only values as if they were at midnight UTC instead of midnight local time. Thus if you are calling your API from a web page, you may want to parse the values yourself, or use a library, or leave them as strings instead of Date objects.
There are certain time zones that have days with forward transitions (such as for DST) right at midnight, meaning the clocks tick from 23:59:59 to 01:00:00. If you specify midnight, some implementations will go forward, some will go backward, and some will error.
If you have to parse a date-only value to a date-time data type, one way to avoid these problems is to assign noon (12:00) instead of midnight (00:00).
Also, you may want to make sure ISO 8601 is indeed the standard you need to comply with. Many people say ISO 8601 when they actually mean RFC 3339. RFC 3339 is mostly compliant with ISO 8601, but only defines a date + time + offset profile. Thus it is appropriate for timestamps, but not whole dates.
Related
I always had conceptual troubles with date values being represented as objects without time (SQL for instance has the type DATE beside DATETIME). The same thinking often creates issues in languages that always store dates along with a time (e.g. C#'s DateTime). Suddenly timezone bugs pop up and the developers insist that all that timezone hullabaloo can be ignored, because their DateTime is actually "just a date". But what does that even mean?
The way I see it, such a "plain date" can be interpreted in only two ways:
From the perspective of points in time (i.e. "instants") one might infer that "2019-09-17" means the start (end) of the day, which is "2019-09-17 00:00:00" ("2019-09-17 23:59:59"). Hence timezone information is relevant and we are not talking about "just a date".
The other option is that the date is supposed to mean the whole day, so we are actually talking about a timespan from "2019-09-17 00:00:00" to "2019-09-17 23:59:59" and timezone information cannot be ignored either.
I argue that all use cases for "plain dates" fall in either of the two categories and that time/timezone can only be ignored if the software will only run on and communicate with systems configured with the exact same timezone.
Can someone provide a counter example or a third interpretation?
The "holiday" is an example of a date without a time, and even without a time zone.
Most holidays are religious in nature, and I don't want to start a religious war, or get sidetracked by minutiae. So as an example holiday, I'm going to pick Earth Day: April 22 of each year in the civil calendar.
If you write software that deals with holidays, said software isn't necessarily dealing with an instant in time across the entire planet (though it could do that in addition to tracking holidays). Instead it carries the concept that maps April 22 of each year to Earth Day. And it is irrelevant that some people will celebrate Earth Day hours before or after other people.
If a client wants to know exactly when Earth Day starts/ends for him, then he can translate "the date" into specific instants of time using his particular time zone. The need for that translation does not diminish the value of the date (say 2020-04-22).
C++20 will have several types to represent a "timezone-less date" such as 2020-04-22 using different data structures:
local_days // day 18374 == April/22/2020
year_month_day // year 2020, month 4, day 22 == April/22/2020
year_month_weekday // year 2020, month 4, 4th Wed == April/22/2020
Ive noticed a change in the way R presents some timezone attributes. For example:
date/time objects with the timezone "America/New_York" present the time zone attribute "EST" (consistent with the format code %Z). This has always been the case and is still the case
other timezones, such as "Asia/Qatar" no longer present the familiar attribute "AST" (for Arabic standard time) as seen previously, but now present "+03".
Why is that and what has changed? When I try to format date/time objects to use the %Z format, I still get "+03" not "AST".
This line shows the issue in practice:
> format(as.POSIXct(Sys.time()), format = "%Z", tz = "Asia/Qatar")
[1] "+03"
This might seem trivial, but legacy code that expects "AST" will no longer work. Any feedback is appreciated.
The source for time zone data in R, and most other computing platforms, is the IANA time zone database. The maintainers of the this data started in 2016, and continuing into 2017, meticulously going through every time zone abbreviation, removing any that they deem "invented", and replacing it with a fixed numeric offset.
By "invented", understand that at earlier times in its history, it was acceptable for the database maintainers to just make up something that seemed reasonable for a time zone abbreviation when there wasn't one naturally used in the real world. This practice has now stopped, and is being reverted, because it was recognized that the database is there to record time zone information from the world, not invent it.
In other words, while the Asia/Qatar time zone entry previously had "GST" as an abbreviation for times before 1972, and "AST" as an abbreviation for times from there to present, neither abbreviation is actually used in Qatar. At least, not to the best knowledge of the database maintainers.
That particular change was made in tzdb 2017a. Announcement here.
I'm computing difference between two dates. One date came from Google Drive's createdDate, other date is from datetime.now(). I'm thinking I should get the localized value of createdDate so that the computed difference is accurate.
Please help or guide me what should I do.
Thanks!
Dates returned in Google Drive's queries are in RFC 3339 format. Default timezone is UTC.
If you are using Python, feed.date.rfc3339 is a RFC 3339 date parser and you might want to use this to interact with Python's native datetime library.
What's the recommended timestamp format for a REST GET API like this:
http://api.example.com/start_date/{timestamp}
I think the actual date format should be ISO 8601 format, such as YYYY-MM-DDThh:mm:ssZ for UTC time.
Should we use the ISO 8601 version without hyphens and colons, such as:
http://api.example.com/start_date/YYYYMMDDThhmmssZ
or should we encode the ISO 8601 format, using for example base64 encoding?
Check this article for the 5 laws of API dates and times HERE:
Law #1: Use ISO-8601 for your dates
Law #2: Accept any timezone
Law #3: Store it in UTC
Law #4: Return it in UTC
Law #5: Don’t use time if you don’t need it
More info in the docs.
REST doesn't have a recommended date format. Really it boils down to what works best for your end user and your system. Personally, I would want to stick to a standard like you have for ISO 8601 (url encoded).
If not having ugly URI is a concern (e.g. not including the url encoded version of :, -, in you URI) and (human) addressability is not as important, you could also consider epoch time (e.g. http://example.com/start/1331162374). The URL looks a little cleaner, but you certainly lose readability.
The /2012/03/07 is another format you see a lot. You could expand upon that I suppose. If you go this route, just make sure you're either always in GMT time (and make that clear in your documentation) or you might also want to include some sort of timezone indicator.
Ultimately it boils down to what works for your API and your end user. Your API should work for you, not you for it ;-).
Every datetime field in input/output needs to be in UNIX/epoch format. This avoids the confusion between developers across different sides of the API.
Pros:
Epoch format does not have a timezone.
Epoch has a single format (Unix time is a single signed number).
Epoch time is not effected by daylight saving.
Most of the Backend frameworks and all native ios/android APIs support epoch conversion.
Local time conversion part can be done entirely in application side depends on the timezone setting of user's device/browser.
Cons:
Extra processing for converting to UTC for storing in UTC format in the database.
Readability of input/output.
Readability of GET URLs.
Notes:
Timezones are a presentation-layer problem! Most of your code shouldn't be dealing with timezones or local time, it should be passing Unix time around.
If you want to store a humanly-readable time (e.g. logs), consider storing it along with Unix time, not instead of Unix time.
RFC6690 - Constrained RESTful Environments (CoRE) Link Format Does not explicitly state what Date format should be however in section 2. Link Format it points to RFC 3986. This implies that recommendation for date type in RFC 3986 should be used.
Basically RFC 3339 Date and Time on the Internet is the document to look at that says:
date and time format for use in Internet protocols that is a
profile of the ISO 8601 standard for representation of dates and
times using the Gregorian calendar.
what this boils down to : YYYY-MM-ddTHH:mm:ss.ss±hh:mm
(e.g 1937-01-01T12:00:27.87+00:20)
Is the safest bet.
Always use UTC:
For example I have a schedule component that takes in one parameter DATETIME.
When I call this using a GET verb I use the following format where my incoming parameter name is scheduleDate.
Example:
https://localhost/api/getScheduleForDate?scheduleDate=2003-11-21T01:11:11Z
For JavaScript,
I normally save date as ISO format by writing: new Date().toISOString();.
Hopefully, it helps with your project.
i am sending the date and time in ( mm/dd/yyyy hh:mm) this format from india to australia( i am booking a date and time for future), for the user in australia it should show him according to his local time. As australia is 5 hrs and 30 mins past to india. how to do it using flex3.
Flex has no timezone calculation support built-in (you can get your local clock's offset and convert between UTC time and local time and that's basically it), your best bet would be to do the conversion via a server-call (with Joda handling the timezone calculations, which includes DST offsets).
First, use the Date class. Second, use UTC values when sending dates (see getUTC family of methods). So when you receive a date, you'll know it is in UTC so you can set up a Date instance with those UTC values (see setUTC family of methods). The class will automatically do the timezone calculations for you and when you present it to the user it will be in their timezone.